@misarblog/mcp

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:

• Open Cursor → Settings → MCP
• Click + Add new MCP server
• Fill in:
  • Name: misarblog
  • Command: npx
  • Args: -y @misarblog/mcp
  • Env: MISARBLOG_API_KEY=mbk_your_key_here
• 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)

• Go to Misar.Blog → Dashboard → Settings → API Keys
• Click Generate API Key — your key starts with mbk_
• 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:

• The MCP server starts a temporary HTTP listener on 127.0.0.1 (random port 9001–9099)
• Your default browser opens to https://www.misar.blog/dashboard/settings/api?mcp_port=<port>
• You click Authorize MCP Access — you must be logged in to Misar.Blog
• The page sends your API key directly to the local listener
• The key is saved to ~/.misarblog/config.json — no clipboard involved
• 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

The server registers 23 tools. Names are used verbatim (e.g. publish_article) — your MCP client selects them from natural-language requests. Most require an mbk_ key; the two public tools (list_comments, get_follow_status) need none.

Area	Tools
Connection & account	login, status, get_profile
Articles & drafts	list_my_articles, get_article, publish_article, create_draft
Series	get_series, create_series, add_to_series
AI writing	research_topic, generate_title_seo, suggest_titles
Images	upload_image, generate_cover_image
Analytics	get_analytics_summary
Comments & follows (public)	list_comments, get_follow_status
Newsletter	list_newsletter_subscribers, list_newsletter_issues
Reactions	get_reactions, add_reaction, remove_reaction

Full parameter tables, return shapes, and example prompts for every tool live in the MCP Tools Reference.

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:

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

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

• 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)