How do I use cnblogs-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@cnblogs-mcp Publish a new blog post titled 'Getting Started with MCP' with markdown content." That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

博客园 MCP 服务

MCP Server Python License

通过 MCP（Model Context Protocol）协议，将博客园 Open API 封装为 AI 可调用的工具。让你在 任何 MCP 客户端（QwenPaw、Claude Desktop、Cline 等）中直接用自然语言发布博客园文章。

功能

✅ create_post — 发布 Markdown 博文到博客园
✅ Token 通过 .env 管理，不含硬编码
✅ 支持任何 MCP 客户端接入

快速开始

1. 克隆 / 下载项目

git clone https://github.com/你的用户名/cnblogs-mcp.git
cd cnblogs-mcp

2. 创建虚拟环境

python -m venv .venv
source .venv/bin/activate      # macOS / Linux
# .venv\Scripts\activate       # Windows

3. 安装依赖

pip install -r requirements.txt

4. 配置 Token

cp .env.example .env

编辑 .env，填入你的博客园 Personal Access Token：

CNBLOGS_TOKEN=your_token_here

5. 运行测试

# 验证 MCP 服务能正常启动
printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}\n{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}\n' \
  | python cnblogs_mcp.py 2>/dev/null | grep '"name"'

正常输出：

{"jsonrpc":"2.0","id":2,"result":{"tools":[{"name":"create_post",...}]}}

获取 Token

登录博客园
进入个人设置 → 安全设置 → Personal Access Token
点击「创建 Token」，填写名称和权限（需要「发表随笔」权限）
复制生成的 Token，填入 .env 文件

⚠️ Token 仅显示一次，请妥善保存。

客户端接入

1. QwenPaw

在 QwenPaw 工作目录下找到 agent.json，添加 MCP 客户端：

{
  "mcp": {
    "clients": {
      "cnblogs": {
        "name": "cnblogs",
        "description": "博客园博文发布",
        "enabled": true,
        "transport": "stdio",
        "command": "/absolute/path/to/cnblogs-mcp/.venv/bin/python",
        "args": ["/absolute/path/to/cnblogs-mcp/cnblogs_mcp.py"],
        "env": {
          "DOTENV_PATH": "/absolute/path/to/cnblogs-mcp/.env"
        }
      }
    }
  }
}

重启 QwenPaw：

qwenpaw daemon restart

2. Claude Desktop

在 ~/Library/Application Support/Claude/claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "cnblogs": {
      "command": "/absolute/path/to/cnblogs-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/cnblogs-mcp/cnblogs_mcp.py"],
      "env": {
        "DOTENV_PATH": "/absolute/path/to/cnblogs-mcp/.env"
      }
    }
  }
}

重启 Claude Desktop。

3. Cline / Roo Code

在 VS Code 设置中搜索「MCP」，找到 MCP Servers，添加：

{
  "cnblogs": {
    "command": "/absolute/path/to/cnblogs-mcp/.venv/bin/python",
    "args": ["/absolute/path/to/cnblogs-mcp/cnblogs_mcp.py"],
    "env": {
      "DOTENV_PATH": "/absolute/path/to/cnblogs-mcp/.env"
    }
  }
}

4. 其他 MCP 客户端

通用配置模板：

参数	值
`command`	`.venv/bin/python`（项目内虚拟环境的 Python）
`args`	`["./cnblogs_mcp.py"]`
`env.DOTENV_PATH`	`.env` 文件的绝对路径

💡 如果 MCP 客户端不支持 DOTENV_PATH，也可以直接用 env.CNBLOGS_TOKEN 传入 token。

手动测试

cd cnblogs-mcp

# 测试 1：初始化 + 工具列表
printf '...' | python cnblogs_mcp.py

# 测试 2：发布一篇博文
printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}\n{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"create_post","arguments":{"title":"测试","body":"## 你好\n\n这是一篇测试文章。"}}}\n' | python cnblogs_mcp.py 2>/dev/null

正常返回：

{"success": true, "postId": 12345678, "postUrl": "https://www.cnblogs.com/你的博客名/p/12345678"}

错误处理

错误信息	原因	解决方案
`未配置 CNBLOGS_TOKEN`	`.env` 未配置或路径错误	检查 `.env` 文件是否存在且 `DOTENV_PATH` 正确
`API 错误: 401`	Token 无效或已过期	重新在博客园创建 Token
`API 错误: 403`	Token 权限不足	创建 Token 时确保勾选「发表随笔」
`API 错误: 400`	请求格式有误	检查 title 和 body 是否为空
`请求超时`	网络问题	检查网络后重试
MCP 连接后工具列表为空	`show_banner` 问题	确保使用 `mcp.run(show_banner=False)`

API 参考

工具：create_post

参数：

参数	类型	必填	说明
`title`	string	✅	博文标题
`body`	string	✅	博文正文（Markdown 格式）
`tags`	array	❌	博文标签（1-5个字符串数组），默认 `["AI随笔"]`

返回值：

{
  "success": true,
  "postId": 19246558,
  "postUrl": "https://www.cnblogs.com/你的博客名/p/19246558"
}

或错误时：

{
  "success": false,
  "error": "错误描述"
}

开发

项目结构

cnblogs-mcp/
├── cnblogs_mcp.py     # MCP 服务主文件
├── requirements.txt   # Python 依赖
├── .env.example       # 环境变量模板（不含真实 Token）
├── .env               # 你的本地配置（已在 .gitignore 中）
├── .gitignore
├── README.md
└── LICENSE

依赖

fastmcp>=3.0.0
python-dotenv>=1.0.0
requests>=2.31.0

License

MIT — 欢迎 Star、 Fork 和 PR！

cnblogs-mcp