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

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 login in Claude Code to authenticate via browser

Fastest path — npx + any MCP client:

# No install needed — just add the config below and run 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 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 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 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 Misar.Blog 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 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 login

If you'd rather not handle the key manually, omit MISARBLOG_API_KEY from the config and run 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 login

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

Tools reference

The server exposes 23 tools. Names are unprefixed — call them exactly as shown (e.g. login, publish_article, get_analytics_summary).

Auth

Tool	Description	Required params
`login`	Browser-based auth — saves key to `~/.misarblog/config.json`	—
`status`	Check whether you're authenticated and which account is connected	—

Articles

Tool	Description	Required params
`list_my_articles`	List your articles, optionally filtered by status	—
`get_article`	Fetch a single article by slug, including full markdown	`slug`
`publish_article`	Publish now or schedule via ISO 8601 datetime	`title`, `body_markdown`
`create_draft`	Save a draft for review in the web editor	`title`, `body_markdown`

AI

Tool	Description	Required params
`research_topic`	Research a topic — insights, sources, and a content outline	`query`
`generate_title_seo`	Generate 5 SEO/AEO/GEO-optimized titles from a topic or keyword	`prompt`
`suggest_titles`	Generate 5 title options from your existing article content	`context`

Images

Tool	Description	Required params
`upload_image`	Upload a local image file to the Misar.Blog CDN	`file_path`
`generate_cover_image`	Generate an AI cover image and upload it to the CDN	`prompt`

Series

Tool	Description	Required params
`get_series`	List all your series	—
`create_series`	Create a new series to group related articles	`title`
`add_to_series`	Add an existing article to a series	`series_slug`, `article_slug`

Comments

Tool	Description	Required params
`list_comments`	Get public comments for an article (no API key required)	`article_id`

Follows

Tool	Description	Required params
`get_follow_status`	Get public follow status and follower count for a user (no API key required)	`user_id`

Tool	Description	Required params
`list_newsletter_subscribers`	Get your newsletter subscriber list	—
`list_newsletter_issues`	Get your sent and scheduled newsletter issues	—

Reactions

Tool	Description	Required params
`get_reactions`	Get reaction counts and your reactions for an article	`article_id`
`add_reaction`	Add a reaction to an article (no-ops if already reacted)	`article_id`, `type`
`remove_reaction`	Remove a specific reaction from an article	`article_id`, `type`

Analytics

Tool	Description	Required params
`get_analytics_summary`	Views, revenue, and subscribers for a time period (up to 365 days)	—

Profile

Tool	Description	Required params
`get_profile`	Your creator profile — username, display name, bio, Stripe status	—

Tool parameters

`login`

Param	Type	Default	Description
`port`	number	random 9001–9099	Local callback port (9001–9099)
`base_url`	string	`https://www.misar.blog`	Misar.Blog base URL for self-hosted instances
`force`	boolean	`false`	Force re-authentication even if already logged in (rotates your API key)

`list_my_articles`

Param	Type	Default	Description
`status`	string	all	Filter: `draft` · `published` · `scheduled` · `archived` (omit for all)
`limit`	number	`20`	Number of articles to return, 1–100

`get_article`

Param	Type	Required	Description
`slug`	string	yes	The article slug

`publish_article`

Param	Type	Required	Description
`title`	string	yes	Article title (max 250 chars)
`body_markdown`	string	yes	Full article body in Markdown
`tags`	string[]	no	Up to 10 tags
`cover_image_url`	string	no	URL of the cover image
`schedule_at`	string	no	ISO 8601 timestamp to schedule; omit to publish immediately
`visibility`	string	no	`public` · `subscribers` · `paid` · `private` (default: `public`)

`create_draft`

Param	Type	Required	Description
`title`	string	yes	Draft title
`body_markdown`	string	yes	Full article body in Markdown
`tags`	string[]	no	Tags for the draft

`research_topic`

Param	Type	Required	Description
`query`	string	yes	Research topic or question (5–500 chars). Be specific for best results

`generate_title_seo`

Param	Type	Required	Description
`prompt`	string	yes	Your topic or target keywords (3–500 chars)
`context`	string	no	Existing article content (plain text or markdown, max 8000 chars) to align titles

`suggest_titles`

Param	Type	Required	Description
`context`	string	yes	Your article content in plain text or markdown (20–8000 chars)

`upload_image`

Param	Type	Required	Description
`file_path`	string	yes	Absolute path to the image file (JPEG, PNG, WebP, or GIF)

`generate_cover_image`

Param	Type	Default	Description
`prompt`	string	—	Description of the image to generate (max 1000 chars)
`size`	string	`1792x1024`	`1024x1024` · `1792x1024` · `1024x1792`

`create_series`

Param	Type	Required	Description
`title`	string	yes	Series title
`description`	string	no	Short description of the series

`add_to_series`

Param	Type	Required	Description
`series_slug`	string	yes	The series slug
`article_slug`	string	yes	The article slug to add
`position`	number	no	1-indexed position; appends to end if omitted

`list_comments`

Param	Type	Default	Description
`article_id`	string	—	UUID of the article to fetch comments for (required)
`limit`	number	`20`	Max results, 1–100
`offset`	number	`0`	Pagination offset

`get_follow_status`

Param	Type	Required	Description
`user_id`	string	yes	UUID of the profile to check follow status for

`list_newsletter_subscribers`

Param	Type	Default	Description
`limit`	number	`20`	Max results, 1–100
`offset`	number	`0`	Pagination offset

`list_newsletter_issues`

Param	Type	Default	Description
`limit`	number	`10`	Max results, 1–50

`get_reactions`

Param	Type	Required	Description
`article_id`	string	yes	UUID of the article

`add_reaction`

Param	Type	Required	Description
`article_id`	string	yes	UUID of the article
`type`	string	yes	Reaction type: `like` · `clap` · `bookmark`

`remove_reaction`

Param	Type	Required	Description
`article_id`	string	yes	UUID of the article
`type`	string	yes	Reaction type to remove: `like` · `clap` · `bookmark`

`get_analytics_summary`

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 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 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 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 `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 23 tools.

Connection refused on `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)

Keywords

mcp

mcp-server

model-context-protocol

blogging

blog

content-publishing

FAQs

What is @misarblog/mcp?

Is @misarblog/mcp popular?

Is @misarblog/mcp well maintained?

Package last updated on 05 Jul 2026

@misarblog/mcp

Misar.Blog MCP Server

Contents

Quick Start

Option A — Python (no dependencies)

1 · Download the script

2 · Verify Python version

3 · Add to your MCP client config

Option B — npm / npx

Option B1 — Zero-install via npx (recommended)

Option B2 — Global install

Option B3 — pnpm / yarn

Verify Node version

Client Setup

Claude Code

Cursor

Windsurf

VS Code (Copilot)

Any other MCP client

Authentication

API Key (recommended)

Browser login (no copy-paste)

Tools reference

Auth

Articles

AI

Images

Series

Comments

Follows

Newsletter

Reactions

Analytics

Profile

Tool parameters

login

list_my_articles

get_article

publish_article

create_draft

research_topic

generate_title_seo

suggest_titles

upload_image

generate_cover_image

create_series

add_to_series

list_comments

get_follow_status

list_newsletter_subscribers

list_newsletter_issues

get_reactions

add_reaction

remove_reaction

get_analytics_summary