Wisewand MCP Server & CLI

Production-ready Model Context Protocol (MCP) server for Wisewand API, enabling AI assistants like Claude to generate SEO-optimized content through natural conversation — plus a wisewand command exposing the same 89 tools in the terminal, for scripts and CI.

Everything you need is on this page. Quick Start installs the server in one command, Command line covers the wisewand binary, and Available tools lists all 89 with their CLI equivalents.

The API's own reference is at https://api.wisewand.ai/docs.

Four longer guides — getting started, installation, a quick reference and the CLI — live in the source repository as docs/guides/. The repository is private and the package ships only dist, this file and the licence, so they are not links: write to [email protected] if you need one.

Features

• 🚀 Complete API Coverage: All Wisewand API endpoints wrapped as MCP tools
• 🔄 Retries on reads, never on writes: a GET is replayed with exponential backoff; a create, update, publish or delete is sent once — see Retries
• 💾 Caching: In-memory, 5-minute TTL, on by default
• 🔒 Security First: Rate limiting, API key management, input validation
• 📊 Optional Metrics: Prometheus endpoint and health checks, off unless asked for
• 🎯 SEO Optimization: Built-in support for all Wisewand SEO features
• 📦 Bulk Operations: Efficient batch processing for large-scale content
• 🌍 Multi-language: Support for French and English with localization
• 📱 Social Media: Generate posts for Instagram, Facebook, X, LinkedIn
• 🎨 Image Generation: Custom images with color palettes and ratios
• 💻 CLI Included: The same tools as wisewand <resource> <verb> — see Command line

Quick Start

👉 New to MCP servers? The two commands below are the whole install. If something goes wrong, Troubleshooting covers every error this server prints.

Prerequisites

• Node.js 20+ (check with node --version)
• npm (comes with Node.js)
• Wisewand API key (Get yours here)
• Claude Desktop or Claude Code CLI

Installation Methods

Option 1: Claude CLI (Easiest) ⭐

For Claude Code CLI users, pass the key on the command line — claude mcp add registers the server, it does not ask you anything:

claude mcp add -e WISEWAND_API_KEY=sk_live_YOUR_KEY_HERE wisewand -- npx -y @wisewandtools/mcp-server

💡 Note: The -- separator is required to pass arguments to the npx command.

Alternative: store the key once, and leave it out of the command.

npm install -g @wisewandtools/mcp-server
wisewand login                                        # prompts, writes ~/.wisewand/config.json (mode 600)
claude mcp add wisewand -- npx -y @wisewandtools/mcp-server

The server reads three sources, in this order: WISEWAND_API_KEY, then a .env in the directory it was started from, then ~/.wisewand/config.json (WISEWAND_CONFIG_DIR relocates it). So a key stored by wisewand login is enough on its own.

It is the CLI's list minus its first entry: nothing constructs the server's argv, so --api-key reaches the CLI and never the server.

Common startup errors, verbatim from src/config/index.ts:

❌ FATAL: No Wisewand API key found.
   Run `wisewand login`, or set WISEWAND_API_KEY. Keys live at https://app.wisewand.ai/api

❌ FATAL: WISEWAND_API_KEY has invalid format (expected sk_live_… or sk_test_…, got abcd123456…)
   Get your API key from https://app.wisewand.ai/api

The second message names whichever source the key came from — --api-key, then WISEWAND_API_KEY, then a .env, then ~/.wisewand/config.json — so there is one place to go and fix it. With one blind spot: dotenv folds a .env into the environment before anything reads it, so a key that came from a file on disk is reported as WISEWAND_API_KEY, and wisewand whoami says environment for both. If the variable is not set in your shell, look for a .env next to you.

The key is checked for shape at startup, not for validity: the server does not call the API until you do. A key that is well-formed but revoked surfaces as a 401 on the first tool call, which the CLI reports as exit code 3.

The server writes two lines to stderr as it starts, whatever the log level — your MCP client captures them, typically into ~/Library/Logs/Claude/mcp*.log:

[wisewand-mcp] Starting Wisewand MCP Server {"version":"3.1.1",…}
[wisewand-mcp] Wisewand MCP Server started successfully {"tools":89,"resources":6,"prompts":4}

Option 2: Claude Desktop (Manual Config)

Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Add this configuration:

{
  "mcpServers": {
    "wisewand": {
      "command": "npx",
      "args": ["-y", "@wisewandtools/mcp-server"],
      "env": {
        "WISEWAND_API_KEY": "sk_live_YOUR_API_KEY_HERE"
      }
    }
  }
}

Restart Claude Desktop and you're ready to go! 🎉

💡 Tip: With npx, the package is always downloaded fresh, so you automatically get the latest version.

🎓 First Time Using Wisewand? Start with the Onboarding Wizard!

After restarting Claude, ask Claude:

Use the onboarding wizard

This interactive guide will teach you:

• ✅ What all 89 tools can do (organized by resource)
• ✅ How to create your first article step-by-step (with actual JSON examples)
• ✅ 5 powerful real-world workflows (SEO series, product reviews, multi-language, etc.)
• ✅ Best practices for quality, SEO optimization, and cost management

Takes 10-15 minutes and you'll be a Wisewand expert!

That wizard is the onboarding_wizard prompt, served by the server itself — nothing to install.

There is also a longer, hands-on Claude Code skill — it walks you through a WordPress connection, a persona, a project and a first published article. It lives in the source repository, which is private, and npm cannot install a Claude Code skill in any case. Write to [email protected] if you want it; the onboarding_wizard prompt above is the path that needs nothing but the server you already have.

Command line (CLI)

The same 89 tools are available as a terminal command, for scripts, cron jobs and CI — no MCP client required. Both ship in one package.

npm install -g @wisewandtools/mcp-server
wisewand setup            # interactive: key, first project, persona, publishing connection

setup is the guided path and asks before it writes anything. If you only need the key stored:

wisewand login            # prompts for your key, stores it in ~/.wisewand/config.json (mode 600)
wisewand whoami           # says which source answered
wisewand logout           # removes the stored key

wisewand projects list                       # table on a terminal, JSON when piped
wisewand articles create "How to brew coffee" --lang en --length 1200
wisewand articles generate <id>              # waits for completion; --no-wait returns immediately
wisewand articles list --json | jq '.items[].id'
wisewand call create_article --input brief.json   # universal escape hatch, stable tool names
wisewand tools --search discover             # explore the registry
wisewand tools describe create_article       # full JSON Schema for a tool

Where the API key comes from, highest priority first: --api-key, then WISEWAND_API_KEY, then a .env in the working directory, then ~/.wisewand/config.json. Set WISEWAND_CONFIG_DIR to relocate that file. wisewand whoami reports which one answered, with one blind spot: dotenv folds a file into the environment before anything reads it, so the second and third both come back as environment.

Output. A table when stdout is a terminal, JSON when redirected or piped, so | jq works with no flags. Pin the format with --json, --table or --markdown in scripts. Logs and progress always go to stderr, never stdout — wisewand articles list > out.json gives you a clean file. NO_COLOR is honoured.

Exit codes. 0 success · 1 generic failure · 2 usage error · 3 authentication (401/403) · 4 not found (404) · 5 rate limited (429) · 130 interrupted.

Bulk input. create_article alone takes 95 properties, so --help shows the required and most common flags and hides the rest (they still work). For anything substantial, pass a whole payload with --input file.json or --input - to read stdin; explicit flags override what the file provides.

The MCP setup is unchanged — npx -y @wisewandtools/mcp-server still starts the server.

Local installation (for development)

The source repository is private, so this section needs access to it. Everything above works from the npm package alone.

Step 1: Clone and Setup

# Clone the repository — needs access
git clone https://github.com/craftwith-ai/mcp-wisewand.git
cd mcp-wisewand

# Install dependencies
npm install

# Copy environment template
cp .env.example .env

Step 2: Configure Your API Key

Edit .env file and add your Wisewand API key:

# Required
WISEWAND_API_KEY=sk_live_YOUR_API_KEY_HERE

# Optional (recommended for production)
NODE_ENV=production
LOG_LEVEL=error
ENABLE_CACHE=true

Every line in .env.example is commented out except the key, and everything it lists is read by something. Copying it as-is turns nothing on.

Step 3: Build the Project

npm run build

This compiles TypeScript to JavaScript in the dist/ folder.

Step 4: Configure Claude Desktop

Find your Claude configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Add this configuration. It is not the same as the one under Option 2 above: that one runs the published package, this one runs your working copy from source. Use one or the other, not both — two entries named wisewand collide.

{
  "mcpServers": {
    "wisewand": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/mcp-wisewand/src/index.ts"],
      "env": {
        "WISEWAND_API_KEY": "sk_live_YOUR_API_KEY_HERE",
        "NODE_ENV": "production",
        "MCP_MODE": "stdio",
        "LOG_LEVEL": "error",
        "ENABLE_CACHE": "true",
        "ENABLE_METRICS": "false"
      }
    }
  }
}

⚠️ IMPORTANT REPLACEMENTS:

1. Replace /absolute/path/to/mcp-wisewand/src/index.ts with your actual path (use pwd to get it)
2. Replace sk_live_YOUR_API_KEY_HERE with your Wisewand API key

💡 Pro Tip: Use npx tsx instead of node dist/index.js for development - it automatically recompiles on changes!

Step 5: Restart Claude Desktop

1. Quit Claude Desktop completely (Cmd+Q on macOS)
2. Reopen Claude Desktop
3. Look for the 🔌 MCP icon at the bottom of the chat window
4. You should see "wisewand" listed as a connected server

Step 6: Verify Installation

In Claude Desktop, type:

Can you list all available Wisewand tools?

You should see 89 tools including create_article, generate_article, publish_to_wordpress, etc.

Installation Verification Checklist

After installation, verify everything works:

• [ ] Dependencies installed: npm install completed without errors
• [ ] Build successful: npm run build completed
• [ ] Server starts: npx tsx src/index.ts runs without errors (Ctrl+C to stop)
• [ ] Claude Desktop config: File exists and has wisewand entry
• [ ] Absolute path: Path in config points to your installation directory
• [ ] API key set: Both .env and claude_desktop_config.json have valid key
• [ ] Claude restarted: Fully quit and reopened Claude Desktop
• [ ] MCP connected: 🔌 icon shows wisewand server in Claude
• [ ] Tools available: Ask Claude "List Wisewand tools" shows 89 tools

Need Help?

If any checkbox fails, see the Troubleshooting section below.

Configuration

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | WISEWAND_API_KEY | Your Wisewand API key (required) | - | | WISEWAND_API_URL | Base URL of the API. The one reason to change it is pointing the client at something other than production | https://api.wisewand.ai | | WISEWAND_TIMEOUT | Request timeout in ms. 30× the slowest answer measured over 77 live calls (median 137 ms, p95 372 ms, max 1 973 ms) | 60000 | | WISEWAND_RETRY_ATTEMPTS | How many times a read is replayed. Writes are never retried except on a 429 — see Retries | 3 | | WISEWAND_RETRY_DELAY | Base delay in ms for that backoff | 1000 | | WISEWAND_CONFIG_DIR | Where the CLI stores its credentials | ~/.wisewand | | NODE_ENV | Environment (development/production) | production | | LOG_LEVEL | Logging level (error/warn/info/debug) | info | | ENABLE_CACHE | Enable the in-memory cache | true | | CACHE_TTL_SECONDS | Default cache lifetime | 300 | | MAX_CACHE_SIZE_MB | Not megabytes. It caps a number of keys: CacheManager passes maxSizeMB * 1000 to NodeCache's maxKeys, so the default bounds the cache at 100 000 entries whatever they weigh | 100 | | MAX_REQUESTS_PER_MINUTE | Rate limit | 60 | | ENABLE_RATE_LIMITING | Apply that rate limit | true | | ENABLE_METRICS | Serve Prometheus metrics on METRICS_PORT | false | | METRICS_PORT | Port for the metrics endpoint, when metrics are on | 9090 | | ENABLE_HEALTH_CHECK | Poll the API every HEALTH_CHECK_INTERVAL ms | false | | HEALTH_CHECK_INTERVAL | That interval, in ms. Each poll is an authenticated GET /v1/projects/ against your own account | 30000 | | NO_COLOR | Set to anything non-empty and the CLI emits no ANSI colour (no-color.org) | unset | | FORCE_COLOR | Set to anything but 0 and the CLI colours its output even when stdout is not a terminal | unset | | TERM | Read for the single value dumb, which turns colour off | inherited | | MCP_MODE | Windows only. stdio suppresses a readline SIGINT handler that fights the stdio transport (src/utils/shutdown.ts). Read nowhere else. | unset |

This table is the whole list, and src/__tests__/docs-truth.test.ts compares it both ways against every process.env. in src/: a variable read and missing here fails, and so does a row nothing reads.

The server itself binds nothing: it speaks MCP over stdio. PORT and HOST used to appear here and were read into the config, where nothing consumed them — they are gone. So are REDIS_* (never forwarded to the cache), TRUSTED_ORIGINS, ENABLE_API_KEY_ROTATION, ENABLE_REQUEST_VALIDATION, ENABLE_TRACING and the five ENABLE_* feature switches: each was parsed, validated, and then read by nobody. A setting that changes nothing is worse than a missing one.

How to Use

Basic Workflow

Once installed, you can use Wisewand through natural conversation with Claude:

1. Create an Article

Simply ask Claude:

Create a blog article about "10 Best SEO Tips for 2024" targeting the keyword "SEO tips 2024" with FAQ and table of contents

Claude will use the create_article tool with the appropriate parameters.

2. Generate Content

Generate the article we just created and wait for completion

Claude will use generate_article to process your content (takes 30-180 seconds).

3. Get the Content

Show me the full article content

Claude will use get_article_output to retrieve the content. The API stores HTML; format: "markdown" converts content, faq and h1 on the way out:

Show me the full article content as markdown

format takes full, html, summary or markdown. Markdown is a reading format — update_article_output writes HTML, so there is no way back.

4. Publish to WordPress (optional)

Publish this article to WordPress as a draft

Claude will use publish_to_wordpress if you have a WordPress connection configured.

Advanced Usage

Create Project for Organization

Create a project called "My Tech Blog" for website techblog.com with English as default language

Define Custom Writing Style

Create a persona called "Tech Expert" with an authoritative tone, technical style, and first-person plural voice

Bulk Content Generation

Create 5 blog articles about: AI basics, Machine Learning, Neural Networks, Deep Learning, and Computer Vision. Auto-generate all of them.

Social Media Generation (NEW!)

Create an article about "AI in Healthcare 2024" with social media posts for Instagram and LinkedIn

Custom Image Generation

Create an article with a featured image using color palette #FF6B6B and #4ECDC4, and inline images with landscape ratio

Complete Workflow Example

Here's a complete example of creating and publishing an article:

Conversation with Claude:

You: "I need to create an SEO article about '10 Best AI Tools for Content Creation'
     targeting the keyword 'AI content tools 2024'. Include FAQ, table of contents,
     and generate a featured image with inline images."

Claude: [Uses create_article tool]
        ✅ Article created with ID: abc-123-def

You: "Great! Now generate the content and wait until it's ready."

Claude: [Uses generate_article tool with wait_for_completion: true]
        ⏳ Generating... (this takes ~60-120 seconds)
        ✅ Article generated successfully!
        - Word count: 2,847 words
        - SEO score: 94/100
        - FAQ: 8 questions generated
        - Images: 1 featured + 3 inline images

You: "Show me the title and excerpt"

Claude: [Uses get_article_output tool]
        📄 Title: "10 Best AI Tools for Content Creation in 2024"
        📝 Excerpt: "Discover the most powerful AI tools transforming
            content creation. From writing assistants to image generators..."

You: "Perfect! Publish this to WordPress as a draft."

Claude: [Uses publish_to_wordpress tool]
        ✅ Published to WordPress as draft
        🔗 URL: https://yourblog.com/wp-admin/post.php?post=456

What Just Happened?

1. Created an article with SEO configuration
2. Generated content using Wisewand AI (with FAQ, TOC, images)
3. Retrieved the output to preview
4. Published to WordPress automatically

All through natural conversation! 🎉

Available tools

89 tools, covering all 88 API operations. The extra one is get_autopilot_status, which reads a project and its feeds — two calls — and reports what autopilot is still missing. This document is the only place the number is written by hand. Everywhere else it is derived — from COMMAND_MAP in the onboarding_wizard prompt and the quick-start resource, from the operation map in registry.test.ts — because the previous arrangement had "66 tools" in seven files, then "74" in four more, and no way to notice either was wrong.

Every tool's input schema is generated from the OpenAPI spec, and src/__tests__/mapping.test.ts compares the two property by property on every run. A field the API does not accept cannot reach a schema, and a field it does accept cannot go missing.

📝 Write, generate and export articles (10)

| Tool | CLI | What it does | |---|---|---| | create_article | wisewand articles create | Create an SEO-optimised article. Only subject is required; every other option falls back to the API… | | generate_article | wisewand articles generate | Generate the content of an existing article. | | get_article | wisewand articles get | Get an article's details and status. | | list_articles | wisewand articles list | List and search articles. | | update_article | wisewand articles update | Update an existing article. Accepts every parameter 'create_article' does. | | get_article_output | wisewand articles output | Get the generated content of an article. | | update_article_output | wisewand articles update-output | Edit the generated content of an article. Get output_id from 'get_article_output' (field all_outputs). | | estimate_article_cost | wisewand articles estimate | Estimate the credit cost of generating one article, before creating it. Takes the same parameters as… | | bulk_create_articles | wisewand articles bulk-create | Create several articles in one call. | | bulk_estimate_cost | wisewand articles bulk-estimate | Estimate the total credit cost of a batch before running it — the way to price 50 creations without… |

📁 Manage projects and their briefs (5)

| Tool | CLI | What it does | |---|---|---| | create_project | wisewand projects create | Create a project. A project holds the brief a generation applies when it is created with… | | get_project | wisewand projects get | Get a project, including its brief configuration, quota and editorial clusters. | | list_projects | wisewand projects list | List projects. Filter on autopilot to see only the autopiloted ones. | | update_project | wisewand projects update | Update a project. This is where autopilot is switched on (autopilot: true), where the brief is… | | delete_project | wisewand projects delete | Delete a project. |

🤖 Unattended content production (1)

| Tool | CLI | What it does | |---|---|---| | get_autopilot_status | wisewand autopilot status | Report whether a project is set up to produce content unattended: the autopilot switch, the brief, the… |

✍️ Manage writing personas (5)

| Tool | CLI | What it does | |---|---|---| | create_persona | wisewand personas create | Create a writing persona. A persona is style (how it writes) plus resume (who it is) — there is no… | | get_persona | wisewand personas get | Get persona details | | list_personas | wisewand personas list | List all personas | | update_persona | wisewand personas update | Update persona settings | | delete_persona | wisewand personas delete | Delete a persona |

🔍 Content discovery and SERP-driven drafts (10)

| Tool | CLI | What it does | |---|---|---| | discover_content | wisewand discover create | Create a Google Discover article, written for the Discover feed rather than for search. Only subject is… | | get_discover_result | wisewand discover get | Get a discover article's details and status. | | list_discover_articles | wisewand discover list | List and search discover articles. | | update_discover_article | wisewand discover update | Update an existing discover article. Accepts every parameter 'discover_content' does. | | run_discovery | wisewand discover run | Generate the content of an existing discover article. | | get_discover_output | wisewand discover output | Get the generated content of a discover article. | | update_discover_output | wisewand discover update-output | Edit the generated content of a discover article. Get output_id from 'get_discover_output' (field… | | estimate_discover_cost | wisewand discover estimate | Estimate the credit cost of generating one discover article, before creating it. Takes the same parameters… | | bulk_create_discover_articles | wisewand discover bulk-create | Create several discover articles in one call. | | bulk_estimate_discover_cost | wisewand discover bulk-estimate | Estimate the total credit cost of a batch before running it — the way to price 50 creations without… |

♻️ Refresh content already published (10)

| Tool | CLI | What it does | |---|---|---| | create_update_post | wisewand update-posts create | Create an update post: a refresh of content already published, rewritten against current sources. Same… | | generate_update_post | wisewand update-posts generate | Generate the content of an existing update post. Closes the produce → refresh loop: articles create… | | get_update_post | wisewand update-posts get | Get an update post's details and status. Closes the produce → refresh loop: articles create content,… | | list_update_posts | wisewand update-posts list | List and search update posts. Closes the produce → refresh loop: articles create content, update posts… | | update_update_post | wisewand update-posts update | Update an existing update post. Accepts every parameter 'create_update_post' does. Closes the produce →… | | get_update_post_output | wisewand update-posts output | Get the generated content of an update post. Closes the produce → refresh loop: articles create content,… | | update_update_post_output | wisewand update-posts update-output | Edit the generated content of an update post. Get output_id from 'get_update_post_output' (field… | | estimate_update_post_cost | wisewand update-posts estimate | Estimate the credit cost of generating one update post, before creating it. Takes the same parameters as… | | bulk_create_update_posts | wisewand update-posts bulk-create | Create several update posts in one call. Closes the produce → refresh loop: articles create content,… | | bulk_estimate_update_post_cost | wisewand update-posts bulk-estimate | Estimate the total credit cost of a batch before running it — the way to price 50 creations without… |

🏪 Category landing pages (10)

| Tool | CLI | What it does | |---|---|---| | create_category_page | wisewand category-pages create | Create a category page — a landing page covering a product or content category. Only subject is required. | | get_category_page | wisewand category-pages get | Get a category page's details and status. | | list_category_pages | wisewand category-pages list | List and search category pages. | | update_category_page | wisewand category-pages update | Update an existing category page. Accepts every parameter 'create_category_page' does. | | generate_category_page | wisewand category-pages generate | Generate the content of an existing category page. | | get_category_page_output | wisewand category-pages output | Get the generated content of a category page. | | update_category_page_output | wisewand category-pages update-output | Edit the generated content of a category page. Get output_id from 'get_category_page_output' (field… | | estimate_category_page_cost | wisewand category-pages estimate | Estimate the credit cost of generating one category page, before creating it. Takes the same parameters as… | | bulk_create_category_pages | wisewand category-pages bulk-create | Create several category pages in one call. | | bulk_estimate_category_page_cost | wisewand category-pages bulk-estimate | Estimate the total credit cost of a batch before running it — the way to price 50 creations without… |

🛍️ Product landing pages (10)

| Tool | CLI | What it does | |---|---|---| | create_product_page | wisewand product-pages create | Create a product page — a landing page for a single product. Only subject is required. | | get_product_page | wisewand product-pages get | Get a product page's details and status. | | list_product_pages | wisewand product-pages list | List and search product pages. | | update_product_page | wisewand product-pages update | Update an existing product page. Accepts every parameter 'create_product_page' does. | | generate_product_page | wisewand product-pages generate | Generate the content of an existing product page. | | get_product_page_output | wisewand product-pages output | Get the generated content of a product page. | | update_product_page_output | wisewand product-pages update-output | Edit the generated content of a product page. Get output_id from 'get_product_page_output' (field… | | estimate_product_page_cost | wisewand product-pages estimate | Estimate the credit cost of generating one product page, before creating it. Takes the same parameters as… | | bulk_create_product_pages | wisewand product-pages bulk-create | Create several product pages in one call. | | bulk_estimate_product_page_cost | wisewand product-pages bulk-estimate | Estimate the total credit cost of a batch before running it — the way to price 50 creations without… |

🚀 Publish content to external platforms (6)

| Tool | CLI | What it does | |---|---|---| | publish_to_wordpress | wisewand publish wordpress | Publish content to WordPress. connection_id must reference a WordPress connection with sufficient permissions. | | publish_to_shopify | wisewand publish shopify | Publish content to a Shopify store. CAUTION: status defaults to "publish" on Shopify — the article goes… | | publish_to_prestashop | wisewand publish prestashop | Publish content to PrestaShop | | publish_to_woocommerce | wisewand publish woocommerce | Publish content to WooCommerce | | trigger_webhook | wisewand publish webhook | Send content via webhook | | get_publish_errors | wisewand publish errors | List unresolved publishing failures. Use this when content generated successfully but never appeared on… |

🔌 Manage platform connections (8)

| Tool | CLI | What it does | |---|---|---| | list_connections | wisewand connections list | List all WordPress and webhook connections | | get_connection | wisewand connections get | Get connection details by ID | | create_connection | wisewand connections create | Create a connection to a publishing platform. Credentials go under encrypted_data, non-secret settings… | | update_connection | wisewand connections update | Update a connection. The body is shaped by type, exactly as in create_connection: credentials under… | | delete_connection | wisewand connections delete | Delete a connection | | get_shopify_blogs | wisewand connections shopify-blogs | List the blogs of a Shopify store, so you can pick the one to publish into. Feed the chosen blog's ID to… | | get_shopify_internal_link_targets | wisewand connections shopify-link-targets | Find products, collections and blog articles in a Shopify store that are relevant to a topic — the… | | update_shopify_connection | wisewand connections shopify-update | Set the target blog, or rename, a Shopify connection. Get blog_id and blog_handle from get_shopify_blogs. |

📡 RSS feed automation (5)

| Tool | CLI | What it does | |---|---|---| | create_feed | wisewand feeds create | Create a new RSS/Atom feed for automated content monitoring and generation | | get_feed | wisewand feeds get | Get feed details and status | | list_feeds | wisewand feeds list | List all configured feeds | | update_feed | wisewand feeds update | Update an existing feed configuration | | delete_feed | wisewand feeds delete | Delete a feed configuration |

⚙️ Inspect and trigger background jobs (2)

| Tool | CLI | What it does | |---|---|---| | get_job | wisewand jobs get | Get the status of a background job | | trigger_job | wisewand jobs trigger | Trigger a named background job |

💳 Credit usage and billing history (2)

| Tool | CLI | What it does | |---|---|---| | list_transactions | wisewand transactions list | List credit transactions and usage history. credits is signed — negative for a payment or a… | | get_daily_transactions | wisewand transactions daily | Get daily transaction summary |

🛠️ Account-level lookups (5)

| Tool | CLI | What it does | |---|---|---| | get_authors | wisewand account authors | List the authors available for WordPress publishing. | | get_author | wisewand account author | Get one WordPress author by ID. | | get_categories | wisewand account categories | List the categories available for WordPress publishing. | | get_category | wisewand account category | Get one WordPress category by ID. | | get_usage_summary | wisewand account usage | Count the entities on the account: articles, category pages, product pages, Discover articles, RSS… |

Usage Examples

Create and Generate an Article

// Create the article. Every option is flat — there is no seo_features or
// image_generation nesting. Pass only what you chose; anything omitted gets the
// API default, not the project brief's (see apply_project_brief_config).
const article = await create_article({
  subject: "10 Best SEO Tips for 2026",
  target_keyword: "SEO tips 2026",
  lang: "en",
  use_faq: true,
  use_toc: true,
  use_boldkeywords: true
});

// Generate the content (polls until it completes)
await generate_article({
  id: article.article_id,
  wait_for_completion: true
});

// Read it back
const output = await get_article_output({
  id: article.article_id
});

Or in one command from the terminal:

wisewand articles write "10 Best SEO Tips for 2026" --project <project-id>

Bulk Content Generation

// Price the batch first — nothing is spent by asking
await bulk_estimate_cost({
  items: [
    { subject: "Topic 1", target_keyword: "keyword1" },
    { subject: "Topic 2", target_keyword: "keyword2" },
    { subject: "Topic 3", target_keyword: "keyword3" }
  ]
});

// Then create them
await bulk_create_articles({
  items: [
    { subject: "Topic 1", target_keyword: "keyword1" },
    { subject: "Topic 2", target_keyword: "keyword2" },
    { subject: "Topic 3", target_keyword: "keyword3" }
  ]
});

API Documentation

Tool Response Format

Every tool returns one text block holding JSON. There is no envelope shared by all of them, and in particular no data key — nothing returns one. What you get is the operation's own fields alongside success:

{
  "success": true,
  "article_id": "…",
  "subject": "How to brew coffee",
  "message": "Article created successfully.",
  "next_steps": ["Generation is already queued — creating an article starts it. …"]
}

A list returns items and count, never articles or total:

{ "success": true, "total": 42, "count": 10, "items": [ … ] }

Failures set isError on the MCP result and carry:

{
  "error": true,
  "message": "API Error 404: …",
  "hint": "…"
}

wisewand tools describe <tool> prints the input schema; the response shape is whatever that operation returns. When in doubt, run the call with --json.

Retries

A read is replayed. A write is not.

| | 429 | 5xx | timeout | dropped connection | |---|---|---|---|---| | GET | retried | retried | retried | retried | | POST / PATCH / DELETE | retried | no | no | no |

A 429 is the only failure that says what the server did: nothing. A 500, a timeout and a dropped connection are indistinguishable from the client — the write may have been carried out in full before the answer went missing — so replaying one is a guess with your account as the stake. This is not hypothetical: before 3.1.0 every method was retried three times, and a single publish_to_wordpress call produced four POSTs to the user's WordPress site, 2, 4 and 6 seconds apart. A create_article that timed out could create four articles and charge four credits.

When a write fails without being replayed, the error says so and names the read that settles it:

API Error 500: {"name":"Error","message":"…"}

This POST was not retried: the API may have carried it out before the failure, so sending it
again could do the work twice. Check with `list_articles` before retrying.

WISEWAND_RETRY_ATTEMPTS and WISEWAND_RETRY_DELAY tune the read side. There is no setting that turns the write side back on.

The spec is the source of truth

docs/openapi/wisewand.json is the API's OpenAPI document, committed to the repository. Everything under src/generated/ is derived from it and committed alongside — the enums (83 languages, 239 countries), the 99 content properties, the 22 project properties, and the inventory of all 88 operations.

This exists because the alternative failed. The tool schemas used to be written by hand, and the API declares additionalProperties: true: a field sent under a name it does not know is accepted and dropped. create_project sent six field names the API has never had, got HTTP 200, created an empty project, and reported success. Nothing — not TypeScript, not the API, not the tests — said otherwise.

npm run sync-spec            # diff the committed spec against the live API
npm run sync-spec -- --write # update it
npm run generate             # regenerate src/generated/ from it
npm run check-coverage       # report operation coverage (88/88)

Three tests keep this honest:

| Test | Fails when | |---|---| | mapping.test.ts | a tool advertises a field the API does not accept, omits one it does, or narrows an enum | | generated-is-fresh.test.ts | src/generated/ was hand-edited, or the spec changed without regenerating | | spec-drift.test.ts | (warns only) the committed spec has fallen behind the live API |

spec-drift deliberately does not fail: the API evolves on its own schedule, and turning someone else's deploy into a red build here would train people to ignore it.

All three compare one document to another. None of them proves the API answers: the suite forces a fake key and stubs fetch, and check-coverage asserts that a string is a key in a Map. That is what npm run verify-live is for — it calls all 88 operations through their MCP tools against the real API, with real credentials and real credits, and confronts each answer with the schema the spec declares, re-reading every write to tell "stored" from "swallowed" apart.

The last pass is committed to the source repository as docs/verification/RAPPORT.md: 81 operations verified, 1 failure, 6 not verifiable — the account has no Shopify, PrestaShop or WooCommerce connection — and 21 verified with a gap worth reading. Every one of those gaps is upstream, and written up in docs/API-NOTES.md, a document meant to be handed to Wisewand. Neither ships in this package; ask [email protected] for a copy.

Known API quirks

• The United Kingdom is uk, not gb. Language and country are Google hl/gl codes. There is no bare pt either — use pt-PT or pt-BR.
• Shopify publishes live by default. publishshopify_status defaults to publish, so use_publishshopify puts the article on the storefront immediately. WordPress defaults to draft. Pass publishshopify_status: "draft" if you want to stage it.
• The project brief does not apply unless you ask for it. apply_project_brief_config defaults to false, so a project_id alone changes nothing about how the content is written. Set it to true and the relation reverses: the brief overrides the values sent beside it — measured on 2026-08-08, an explicit lang was replaced by the brief's own and two articles had to be thrown away. Omitting an option never hands the decision to the brief; it sends nothing and gets the API default named in that option's description.
• The project quota lives in feeds_config. The spec also declares quota_limit and friends at the top level, but the backend rejects them there.
• An entity cannot be updated in its first minute. update_* on something created seconds earlier answers 400 Cannot update entity created less than a minute ago. Nothing in the spec says so; wait and retry.
• The generated text is not on the entity. get_article answers with the entity — its id, status, title, cover image, timestamps, and data.input carrying back every parameter the generation was given. What it never carries is the article: content, h1, faq and the social posts live one call further, at get_article_output. Same for get_category_page / get_category_page_output and get_product_page / get_product_page_output.
• content, faq and h1 are HTML, though the spec types them as plain strings. Read them with format: "markdown" if you want text.
• A newly created entity reports status: "prequeued", which the spec's enum does not list. It becomes queued within seconds.
• The generation can call you back, instead of you polling it. use_webhook: true plus webhook_connection_id on a create or an update fires a request at a connection of type: "webhook" once the content is generated — create one with POST /v1/connections/, which carries the URL, so a single connection can serve every entity. It is easy to miss: the API declares the two fields and one sentence about them, and nothing else — no payload schema, no signature scheme, no retry policy, and no statement about whether a failed generation notifies too. This client passes both fields through and has never exercised the callback, so treat everything past "it exists" as unverified.

The upstream half of that list, with the measurement behind each item, is in docs/API-NOTES.md in the source repository — twenty-five findings, each with the call that established it.

Monitoring

Health Check

curl http://localhost:9090/health

Metrics

curl http://localhost:9090/metrics

Available Metrics

• mcp_tool_calls_total - Total tool calls, by tool and outcome
• mcp_tool_call_duration_ms - Tool execution time
• wisewand_api_calls_total - API calls to Wisewand, by endpoint and outcome

Plus whatever prom-client collects by default — process CPU, memory, event-loop lag.

Three, and every one of them moves. There used to be five listed and eight registered: mcp_active_connections, cache_hits_total, cache_misses_total, mcp_errors_total and wisewand_api_call_duration_ms had no caller anywhere, so each sat at zero for the life of every process — a dashboard built on the first would have shown a server with no clients, and one built on the fourth a server that never errs. src/__tests__/monitoring.test.ts now compares this list to what MetricsCollector registers, in both directions, and fails on a metric nothing can move.

Development

Running in Development Mode

npm run dev

Running Tests

npm test
npm run test:coverage

Linting

npm run lint
npm run format

Type Checking

npm run typecheck

Architecture

src/
├── index.ts             # MCP entrypoint (stdio)
├── cli.ts               # CLI entrypoint — the second projection of the registry
├── core/                # What both entrypoints share
│   ├── registry.ts      #   the tool set, built once
│   └── context.ts       #   apiClient / cache / metrics wiring
├── cli/                 # Terminal surface only
│   ├── commands.ts      #   tool name → command group and verb
│   ├── flags.ts         #   JSON Schema → flags, and coercion
│   ├── credentials.ts   #   key resolution and ~/.wisewand/config.json
│   ├── render.ts        #   table / JSON output
│   ├── workflows.ts     #   composed multi-tool commands
│   └── errors.ts        #   exit codes
├── generated/           # Derived from docs/openapi/wisewand.json — do not edit
│   ├── enums.ts         #   83 languages, 239 countries, and the rest
│   ├── content-params.ts
│   ├── project-params.ts
│   ├── persona-params.ts
│   ├── operations.ts    #   the inventory of all 88 operations
│   └── entities.ts      #   response types
├── server/              # Core MCP server
│   └── WisewandMCPServer.ts
├── clients/             # API client
│   └── WisewandAPIClient.ts
├── handlers/            # Request handlers
│   ├── tools/           #   tool implementations, incl. content/ (the 5 families)
│   ├── resources/       #   wisewand:// schemas and guides
│   └── prompts/         #   prompt templates
├── services/            # CacheManager, RateLimiter
├── monitoring/          # MetricsCollector, HealthChecker
├── config/              # Environment → typed config, loaded lazily
├── types/               # TypeScript definitions
├── utils/               # logger, shutdown, tool helpers
└── __tests__/           # The suite

Performance

• Throughput: one global bucket of 60 requests/minute, MAX_REQUESTS_PER_MINUTE
• Caching: in-memory, 5-minute TTL, per process
• Concurrency: one MCP client per process, over stdio — the transport is a pipe, so "simultaneous connections" is not a thing this server has

Response time is the Wisewand API's, not this server's: a generation runs for minutes, and generate_* polls until it finishes or max_wait_time runs out.

Security

• ✅ API key authentication
• ✅ Input validation against the API's own schema, before any request is sent
• ✅ The stored credential file is written 0600, in a 0700 directory, and the CLI warns when it finds it looser
• ✅ No sensitive data in logs
• ⚠️ Rate limiting is one global bucket, not per client: a single process serves a single client, so there is nothing to tell apart
• ⚠️ There is no Dockerfile in this repository, so it makes no claim about how a container built from it runs

Troubleshooting

Claude Desktop Integration Issues

Problem: MCP server not showing up in Claude

Solutions:

1. Verify configuration file location

   # macOS - check if file exists
   cat ~/Library/Application\ Support/Claude/claude_desktop_config.json
   
   # Should show your wisewand configuration

2. Check absolute path

   # Get absolute path of your installation
   cd /path/to/mcp-wisewand
   pwd
   # Use this EXACT path in claude_desktop_config.json

3. Verify API key format

   • Must start with sk_live_
   • No extra spaces or quotes
   • Check at app.wisewand.ai/api

4. Check server logs

   # Start it by hand; it announces itself on stderr and waits for JSON-RPC
   # on stdin. Ctrl-D ends it.
   npx -y @wisewandtools/mcp-server
   # [wisewand-mcp] Wisewand MCP Server started successfully {"tools":89,…}

   Your client keeps the same two lines. On macOS with Claude Desktop they are in ~/Library/Logs/Claude/mcp*.log.

5. Restart Claude Desktop properly

   • Fully quit (Cmd+Q, not just close window)
   • Wait 5 seconds
   • Reopen Claude Desktop
   • Check MCP icon 🔌 at bottom

Problem: "Module not found" errors

Solution:

# Reinstall dependencies
rm -rf node_modules package-lock.json
npm install

# Rebuild
npm run build

Problem: API key authentication fails

Solutions:

1. Verify key in .env matches claude_desktop_config.json
2. Check key hasn't expired at Wisewand dashboard
3. Test API key directly:

   curl https://api.wisewand.ai/v1/articles/ \
     -H "Authorization: Bearer sk_live_YOUR_KEY"

Problem: Tools not appearing in Claude

Solutions:

1. Check MCP connection status in Claude Desktop
2. Look for error messages in Claude's developer console:
   • macOS: ~/Library/Logs/Claude/mcp*.log
3. Verify all 89 tools are loaded:

   # Ask Claude: "List all Wisewand tools"
   # Should show: create_article, generate_article, etc.

General Issues

1. Rate Limiting (429 errors)

   • Wisewand API: 60 requests/minute
   • Adjust MAX_REQUESTS_PER_MINUTE in .env
   • Use bulk operations for multiple articles

2. Connection Timeouts

   • No request waits for a generation: generate_* starts the run and polls get_* every five seconds, so nothing is held open for minutes
   • Increase WISEWAND_TIMEOUT in .env (default: 60000ms) only if your link needs more than a minute for a single request
   • Use wait_for_completion: true in generate_article

3. Cache Issues

   • Clear cache: Restart MCP server (restart Claude Desktop)
   • Disable cache: Set ENABLE_CACHE=false in config

4. Memory Usage

   • Monitor with: Ask Claude "Check Wisewand server health"
   • Reduce MAX_CACHE_SIZE_MB if needed

Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Open a Pull Request

License

MIT License - see LICENSE file for details

Support

• Documentation: https://api.wisewand.ai/docs
• Bugs and questions: [email protected] — the source repository is private, so there is no public issue tracker. npm bugs @wisewandtools/mcp-server opens the same address.

Changelog

The full history lives in CHANGELOG.md in the source repository, which is the one place it is kept. It does not ship in this package — the tarball is dist, this file and the licence — and the repository is private, so there is no link to give you. Every published version is listed at https://www.npmjs.com/package/@wisewandtools/mcp-server?activeTab=versions.

This section used to hold its own copy, and it stopped at v2.0.12 in a package stamped 3.0.0 — two majors behind, in the document most readers open first. A changelog maintained in two places is maintained in neither.

Current release: v3.2.0 — one new command and two boundaries drawn. wisewand account credits prints the balance in a terminal, read from a pricing call that creates and charges nothing. The package no longer declares an entry point it could not honour: importing it used to start an MCP server inside the caller's process, and now fails with a resolution error. And the OpenAPI spec, whose info.version has been 0.0.1 since the first fetch, gained a provenance sidecar so "is this current?" has an answer.

FAQ

How much does it cost to generate articles?

Use the estimate_article_cost tool to calculate costs before generation. Typical costs:

• Blog post (1000 words): ~10-20 credits
• With images: +5-10 credits
• With social media posts: +2-5 credits

Can I use this without Claude Desktop?

Yes. It is a Node process speaking MCP over stdio, so any MCP-compatible client can launch it — and the same tools are available as the wisewand command for scripts and CI.

Where can I get a Wisewand API key?

Visit wisewand.ai and sign up for an account. API keys are available in your dashboard.

How long does article generation take?

• Article creation: ~1 second
• Content generation: 30-180 seconds (depending on length and features)
• Use wait_for_completion: true to wait automatically

Built with ❤️ by Wisewand Team