博客园 MCP 服务

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

---

功能

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

---

目录

• 快速开始
• 获取 Token
• 客户端接入
  • QwenPaw
  • Claude Desktop
  • Cline / Roo Code
  • 其他 MCP 客户端
• 手动测试
• 错误处理
• API 参考

---

快速开始

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

1. 登录 博客园
2. 进入 个人设置 → 安全设置 → Personal Access Token
3. 点击「创建 Token」，填写名称和权限（需要「发表随笔」权限）
4. 复制生成的 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 格式）

返回值：

{
  "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！