Misar.Blog MCP Server

Connect Claude Code, Cursor, Windsurf, or any MCP-compatible AI assistant to your Misar.Blog account. Publish articles, manage drafts, generate cover images, and pull analytics — all from your AI coding environment.

Two runtimes are available — choose based on what you already have installed:

| Runtime | Requires | Best for | | ------- | -------- | -------- | | Python (recommended) | Python 3.11+ · stdlib only | Claude Code, any lightweight setup | | npm / npx | Node.js 18+ | Node-first workflows, CI/CD |

Contents

• Quick Start
• Option A — Python
• Option B — npm / npx
• Client Setup
  • Claude Code
  • Cursor
  • Windsurf
  • VS Code (Copilot)
  • Any other MCP client
• Authentication
  • API Key (recommended)
  • Browser login (no copy-paste)
• Tools reference
• Usage examples
• Self-hosted Misar.Blog
• Troubleshooting

Quick Start

Fastest path — Python + Claude Code:

# 1. Copy the server script
cp packages/mcp/misarblog-mcp.py ~/.claude/scripts/misarblog-mcp.py
chmod +x ~/.claude/scripts/misarblog-mcp.py

# 2. Add to Claude Code MCP settings (see below)

# 3. Run misarblog_login in Claude Code to authenticate via browser

Fastest path — npx + any MCP client:

# No install needed — just add the config below and run misarblog_login

Option A — Python (no dependencies)

Uses Python's standard library only. No pip install required. Works on macOS, Linux, and Windows (with Python 3.11+).

1 · Download the script

If you cloned the MisarBlog repo:

cp packages/mcp/misarblog-mcp.py ~/.claude/scripts/misarblog-mcp.py
chmod +x ~/.claude/scripts/misarblog-mcp.py

Direct download (one-liner):

mkdir -p ~/.claude/scripts
curl -fsSL https://www.misar.blog/mcp/misarblog-mcp.py -o ~/.claude/scripts/misarblog-mcp.py
chmod +x ~/.claude/scripts/misarblog-mcp.py

2 · Verify Python version

python3 --version   # must be 3.11 or later

If you're on macOS with an older system Python, use Homebrew: brew install python.

3 · Add to your MCP client config

{
  "mcpServers": {
    "misarblog": {
      "command": "python3",
      "args": ["~/.claude/scripts/misarblog-mcp.py"],
      "env": {
        "MISARBLOG_API_KEY": "mbk_your_key_here"
      }
    }
  }
}

You can omit MISARBLOG_API_KEY if you plan to use the misarblog_login browser flow.

Option B — npm / npx

Uses Node.js 18+ with the @modelcontextprotocol/sdk. npx fetches and caches the package on first run — no manual install needed.

Option B1 — Zero-install via npx (recommended)

{
  "mcpServers": {
    "misarblog": {
      "command": "npx",
      "args": ["-y", "@misarblog/mcp"],
      "env": {
        "MISARBLOG_API_KEY": "mbk_your_key_here"
      }
    }
  }
}

Option B2 — Global install

npm install -g @misarblog/mcp

Then use misarblog-mcp as the command:

{
  "mcpServers": {
    "misarblog": {
      "command": "misarblog-mcp",
      "env": {
        "MISARBLOG_API_KEY": "mbk_your_key_here"
      }
    }
  }
}

Option B3 — pnpm / yarn

pnpm add -g @misarblog/mcp
# or
yarn global add @misarblog/mcp

Verify Node version

node --version   # must be v18 or later

Client Setup

Claude Code

Claude Code stores MCP server config in ~/.claude/settings.json.

Edit the file:

# Open in your editor
code ~/.claude/settings.json

Add the mcpServers block (create settings.json if it doesn't exist):

{
  "mcpServers": {
    "misarblog": {
      "command": "python3",
      "args": ["~/.claude/scripts/misarblog-mcp.py"],
      "env": {
        "MISARBLOG_API_KEY": "mbk_your_key_here"
      }
    }
  }
}

Reload Claude Code — MCP servers start automatically on the next session. You'll see misarblog listed when you run /mcp in any Claude Code session.

Verify the connection:

> call misarblog_get_profile

Claude Code should return your username, display name, and account status.

Cursor

Cursor stores MCP config at ~/.cursor/mcp.json (global) or .cursor/mcp.json inside a project (project-scoped, takes priority).

Global config (~/.cursor/mcp.json):

{
  "mcpServers": {
    "misarblog": {
      "command": "npx",
      "args": ["-y", "@misarblog/mcp"],
      "env": {
        "MISARBLOG_API_KEY": "mbk_your_key_here"
      }
    }
  }
}

Alternative — via Cursor Settings UI:

1. Open Cursor → Settings → MCP
2. Click + Add new MCP server
3. Fill in:
   • Name: misarblog
   • Command: npx
   • Args: -y @misarblog/mcp
   • Env: MISARBLOG_API_KEY=mbk_your_key_here
4. Click Save — Cursor restarts the MCP daemon automatically.

Verify: open Cursor Agent mode → type use misarblog_get_profile — the tool card should appear.

Windsurf

Windsurf reads MCP config from ~/.codeium/windsurf/mcp_config.json.

{
  "mcpServers": {
    "misarblog": {
      "command": "npx",
      "args": ["-y", "@misarblog/mcp"],
      "env": {
        "MISARBLOG_API_KEY": "mbk_your_key_here"
      }
    }
  }
}

Reload Windsurf after saving. The MCP tools appear under the Cascade panel → Tools.

VS Code (Copilot)

VS Code reads MCP config from .vscode/mcp.json in the workspace root, or from User Settings (settings.json) under "mcp".

Workspace config (.vscode/mcp.json):

{
  "servers": {
    "misarblog": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@misarblog/mcp"],
      "env": {
        "MISARBLOG_API_KEY": "mbk_your_key_here"
      }
    }
  }
}

User settings (settings.json):

{
  "mcp": {
    "servers": {
      "misarblog": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "@misarblog/mcp"],
        "env": {
          "MISARBLOG_API_KEY": "mbk_your_key_here"
        }
      }
    }
  }
}

Restart VS Code after saving. The misarblog_* tools appear in GitHub Copilot Chat when you enable Agent mode (the @ icon in the chat panel).

Any other MCP client

Any MCP-compatible client that supports stdio servers works with the same pattern:

• Command: python3 (Python) or npx (npm)
• Args: ["~/.claude/scripts/misarblog-mcp.py"] or ["-y", "@misarblog/mcp"]
• Transport: stdio
• Env: MISARBLOG_API_KEY=mbk_... (or use misarblog_login after connecting)

Authentication

API Key (recommended)

1. Go to Misar.Blog → Dashboard → Settings → API Keys
2. Click Generate API Key — your key starts with mbk_
3. Copy it and paste into the MISARBLOG_API_KEY env var in your MCP config

Keys have a 100 req/min rate limit. You can revoke and regenerate at any time from the settings page.

Precedence order:

MISARBLOG_API_KEY env var  →  ~/.misarblog/config.json  →  prompt to run misarblog_login

Browser login (no copy-paste)

If you'd rather not handle the key manually, omit MISARBLOG_API_KEY from the config and run misarblog_login as your first tool call. The flow:

1. The MCP server starts a temporary HTTP listener on 127.0.0.1 (random port 9001–9099)
2. Your default browser opens to https://www.misar.blog/dashboard/settings/api?mcp_port=<port>
3. You click Authorize MCP Access — you must be logged in to Misar.Blog
4. The page sends your API key directly to the local listener
5. The key is saved to ~/.misarblog/config.json — no clipboard involved
6. All subsequent tool calls use this saved key automatically

The listener accepts connections from 127.0.0.1 only and shuts down after 120 seconds.

Example prompt:

Connect my Misar.Blog account using misarblog_login

Claude will call the tool, open your browser, and confirm once you've authorized.

Tools reference

| Tool | Description | Required params | | ---- | ----------- | --------------- | | misarblog_login | Browser-based auth — saves key to ~/.misarblog/config.json | — | | misarblog_get_profile | Username, display name, bio, subscriber count, Stripe status | — | | misarblog_list_articles | List your articles by status | — | | misarblog_get_article | Fetch a single article with full body | slug | | misarblog_publish_article | Publish now or schedule via ISO 8601 datetime | title, body_markdown | | misarblog_create_draft | Save a draft for review in the web editor | title, body_markdown | | misarblog_upload_image | Upload a local file to the Misar.Blog CDN | file_path | | misarblog_generate_image | Generate an AI cover image from a text prompt | prompt | | misarblog_list_series | List all article series on your account | — | | misarblog_create_series | Create a new series | title | | misarblog_add_to_series | Add an article to a series at a given position | series_slug, article_slug | | misarblog_get_analytics | Views, revenue, and subscriber trends (up to 365 days) | — |

Tool parameters

misarblog_login

| Param | Type | Default | Description | | ----- | ---- | ------- | ----------- | | port | number | random 9001–9099 | Local callback port | | base_url | string | https://www.misar.blog | Override for self-hosted instances |

misarblog_list_articles

| Param | Type | Default | Description | | ----- | ---- | ------- | ----------- | | status | string | published | One of: draft · published · scheduled · archived | | limit | number | 20 | Max results, 1–100 |

misarblog_publish_article

| Param | Type | Required | Description | | ----- | ---- | -------- | ----------- | | title | string | yes | Article title (max 250 chars) | | body_markdown | string | yes | Full article content in Markdown | | tags | string[] | no | Up to 10 tags | | cover_image_url | string | no | HTTPS URL of cover image | | schedule_at | string | no | ISO 8601 datetime to publish later (e.g. 2025-06-01T09:00:00Z) | | visibility | string | no | public · subscribers · paid · private (default: public) |

misarblog_create_draft

| Param | Type | Required | Description | | ----- | ---- | -------- | ----------- | | title | string | yes | Draft title | | body_markdown | string | yes | Content in Markdown | | tags | string[] | no | Up to 10 tags |

misarblog_upload_image

| Param | Type | Required | Description | | ----- | ---- | -------- | ----------- | | file_path | string | yes | Absolute local path (jpg, png, webp, gif, svg) |

misarblog_generate_image

| Param | Type | Default | Description | | ----- | ---- | ------- | ----------- | | prompt | string | — | Image description (max 1000 chars) | | size | string | 1024x1024 | 1024x1024 · 1792x1024 · 1024x1792 |

misarblog_create_series

| Param | Type | Required | Description | | ----- | ---- | -------- | ----------- | | title | string | yes | Series name | | description | string | no | Short description |

misarblog_add_to_series

| Param | Type | Required | Description | | ----- | ---- | -------- | ----------- | | series_slug | string | yes | URL slug of the series | | article_slug | string | yes | URL slug of the article | | position | number | no | 1-indexed position; appends to end if omitted |

misarblog_get_analytics

| Param | Type | Default | Description | | ----- | ---- | ------- | ----------- | | days | number | 30 | Look-back window, 1–365 |

Usage examples

These are prompts you can send directly in Claude Code or Cursor Agent mode:

Publish a new article:

Write a 1000-word article about "Why AI-first blogging changes SEO forever"
and publish it on my Misar.Blog with tags ["AI", "SEO", "blogging"].

Draft with a generated cover image:

Generate a dark, futuristic cover image for an article titled "Building with MCP".
Then create a draft with that image as the cover.

Check performance:

Show me my analytics for the last 90 days.

Publish on a schedule:

Write a short announcement post and schedule it to publish tomorrow at 9am UTC.

Organize a series:

List my articles with status "published", then create a series called "AI Writing Guide"
and add the last 3 articles to it in chronological order.

Self-hosted Misar.Blog

If you run your own Misar.Blog instance, set MISARBLOG_BASE_URL to your domain:

{
  "mcpServers": {
    "misarblog": {
      "command": "python3",
      "args": ["~/.claude/scripts/misarblog-mcp.py"],
      "env": {
        "MISARBLOG_API_KEY": "mbk_your_key_here",
        "MISARBLOG_BASE_URL": "https://blog.yourdomain.com"
      }
    }
  }
}

MISARBLOG_BASE_URL can also be stored in ~/.misarblog/config.json (written by misarblog_login):

{
  "api_key": "mbk_...",
  "username": "yourname",
  "base_url": "https://blog.yourdomain.com"
}

Troubleshooting

"Not configured" on every tool call

The server can't find your API key. Either:

• Set MISARBLOG_API_KEY in the MCP config env block, or
• Run misarblog_login once to save it to ~/.misarblog/config.json

"API key invalid or expired"

Your key was revoked. Go to Dashboard → Settings → API Keys and generate a new one, or run misarblog_login again to get a fresh key via the browser flow.

"Rate limited (100 req/min)"

You've exceeded the API rate limit. Wait 60 seconds and retry. If you're running automated pipelines, add a short delay between tool calls.

Browser doesn't open during misarblog_login

The server prints the URL to stderr when webbrowser.open() fails. Copy and open it manually:

Open this URL in your browser:
  https://www.misar.blog/dashboard/settings/api?mcp_port=9042

You have 120 seconds from when the tool runs to click Authorize MCP Access.

python3: command not found

• macOS: brew install python or install from python.org
• Linux: sudo apt install python3 / sudo dnf install python3
• Windows: Install from python.org and ensure python3 is in PATH

Alternatively, switch to the npm/npx option — it only requires Node.js.

npx is slow on first run

npx -y @misarblog/mcp downloads the package on first run and caches it locally. Subsequent starts are instant. If startup time matters, use npm install -g @misarblog/mcp instead.

MCP server doesn't appear in Claude Code

Run /mcp in a Claude Code session to list active servers. If misarblog is missing:

1. Check ~/.claude/settings.json — ensure the mcpServers.misarblog block is valid JSON

2. Verify the script path: ls -la ~/.claude/scripts/misarblog-mcp.py

3. Test the server directly:

   printf '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}\n' \
     | MISARBLOG_API_KEY=mbk_test python3 ~/.claude/scripts/misarblog-mcp.py

   You should see a JSON response listing 12 tools.

Connection refused on misarblog_login callback

The local HTTP server binds to 127.0.0.1. If your browser opens on a different machine (e.g. remote VS Code over SSH), the callback won't reach the MCP server. In that case, use the API Key method instead.

Requirements

• Python runtime: Python 3.11+ · no external packages
• npm runtime: Node.js 18+ · package fetched automatically via npx
• Account: Misar.Blog creator account (sign up free)