Skip to main content
Glama

csdn-mcp

让 AI Agent 通过 MCP 协议管理 CSDN 博客:发布、查询、修改、删除、上传图片。

License: MIT Node.js CI MCP

30 秒快速开始

git clone https://github.com/Leaderxin/csdn-mcp.git
cd csdn-mcp
npm install
npm run build

然后把下面这段加进 MCP 客户端配置(args 必须是 dist/index.js 的绝对路径):

{
  "mcpServers": {
    "csdn": {
      "command": "node",
      "args": ["/absolute/path/to/csdn-mcp/dist/index.js"],
      "env": {
        "CSDN_COOKIE": "把整段 Cookie 粘到这里",
        "CSDN_LOG_LEVEL": "warn"
      }
    }
  }
}

CSDN_COOKIE 是唯一必填项,没有它任何写操作都会返回 AUTH_MISSING。获取方式见 docs/CONFIGURATION.md。

Related MCP server: juejin-release-mcp

工具一览

11 个工具,全部走 stdio。参数、返回结构、错误码的完整定义见 docs/TOOLS.md。

工具

说明

auth_login

运行期设置 Cookie,随后所有请求立即生效,无需重启进程

auth_status

检查当前 Cookie 是否已配置、格式是否合法、账号名是什么

publish_article

新建文章;mode 默认 draft,发布必须显式传 mode: "publish"

update_article

更新已有文章;改标题/标签/摘要/封面 + 草稿副本

get_article

按 ID 读取单篇文章,可选是否带正文

list_articles

列出文章;scope=published 只看已发布,scope=all 含草稿与分类计数

delete_article

删除文章,默认进回收站,permanent: true 彻底删除

upload_image

上传本地图片,返回公网 URL,分 cover / body 两条通道

list_categories

列出文章分类;接口不可用时回退到内置列表

list_tags

列出常用标签;接口不可用时回退到内置列表

verify_article

回查 API 状态 + 公开页 HTTP 码,确认文章真实状态

一次真实的 Agent 调用流程

用户:把这篇《MCP 协议入门》给我发成草稿,先别公开。

Agent → publish_article({
          "title": "MCP 协议入门",
          "markdown": "# MCP 协议入门\n\n...",
          "tags": ["MCP", "TypeScript"],
          "categories": "后端"
        })
← { "articleId": "149234567",
    "url": "https://blog.csdn.net/Leaderxin/article/details/149234567",
    "state": "draft",
    "verification": { "articleId": "149234567", "state": "draft", "statusCode": 2,
                      "publicStatusCode": 404, "consistent": true,
                      "message": "草稿已确认:接口 status=2,公开页 404" } }

Agent → verify_article({ "article_id": "149234567", "expected": "draft" })
← { "articleId": "149234567", "state": "draft", "statusCode": 2,
    "publicStatusCode": 404, "consistent": true, "message": "..." }

用户:内容我看过了,发布吧。

Agent → update_article({ "article_id": "149234567", "mode": "publish" })
← { "articleId": "149234567",
    "url": "https://blog.csdn.net/Leaderxin/article/details/149234567",
    "state": "published" }

Agent → verify_article({ "article_id": "149234567", "expected": "publish" })
← { "articleId": "149234567", "state": "published", "statusCode": 1,
    "publicStatusCode": 200, "consistent": true, "message": "..." }

注意 publish_article 在步骤 1 里没有传 mode —— 默认就是草稿。只有用户在步骤 3 明确要求之后,Agent 才发出版本。原因见 docs/TOOLS.md。

配置项

完整说明(含"什么时候需要改")见 docs/CONFIGURATION.md。

变量

默认值

作用

CSDN_COOKIE

""

认证凭据。所有写操作的必填项

CSDN_USERNAME

""

Cookie 里没有 UserName 时使用

CSDN_LOG_LEVEL

warn

silent / error / warn / info / debug,日志走 stderr

CSDN_TIMEOUT_MS

20000

单次请求超时

CSDN_MAX_RETRIES

2

可重试失败的额外尝试次数

CSDN_MIN_INTERVAL_MS

250

普通请求之间的最小间隔

CSDN_SAVE_INTERVAL_MS

11000

写操作之间的最小间隔(CSDN 约 10s 内会拒绝)

CSDN_API_BASE

https://bizapi.csdn.net

bizapi 网关地址

CSDN_BLOG_BASE

https://blog.csdn.net

公开页地址,用于写后校验

CSDN_COMMUNITY_BASE

https://blog.csdn.net

社区列表接口地址

CSDN_USER_AGENT

Chrome 131 UA

请求头 User-Agent

CSDN_APP_KEY

203803574

bizapi 网关 app key(公开常量)

CSDN_APP_SECRET

9znpamsyl2c7cdrr9sas0le9vbc3r6ba

bizapi 网关签名密钥

它是怎么工作的

HMAC 签名。 所有走 bizapi.csdn.net 的请求都要带 X-Ca-Signature。签名串由 method、accept、content-type、x-ca-key、x-ca-nonce 和含查询串的 uri 按固定换行拼成,再做 base64(HMAC-SHA256(appSecret, stringToSign));同时必须带 X-Ca-Signature-Headers: x-ca-key,x-ca-nonce 告诉网关哪几个 header 参与了签名。少一行就是 401 HMAC signature does not match。完整格式见 docs/API-NOTES.md。

两步图片上传。 先 POST /resource-api/v1/image/direct/upload/signature 拿上传凭据,再 multipart 直传到返回的存储 host,响应里的 data.imageUrl 才是公网地址。正文图和封面图是两条不同的通道(appName 不同),不可互换。见 docs/TOOLS.md。

为什么每次写入都要回查公开页。 saveArticle 返回 200 不等于成功。接口里的 status 表达的是"这篇文章是否对外可见",不是"这次调用算不算草稿"——两者共用同一组数字编码(0 / 1 已发布,2 草稿,6 审核拒绝,16 审核中),写入用的值和 getArticle 报回来的值含义并不对称(发布时发的是 0,getArticle 报的是 1)。所以 publish_article / update_article 默认跑一次校验:既看 API 返回的 status,也真的去请求一次公开页,只有两边都说"是草稿"(公开页 404)或都说"已发布"(公开页 200)才判定 consistent: true。任何一边不一致都会如实报告,不会因为一个 200 就宣称"发布成功"。

文档

文档

内容

docs/README.md

文档索引

docs/GETTING-STARTED.md

从零到第一次成功调用

docs/TOOLS.md

11 个工具的参数、返回、错误码

docs/CONFIGURATION.md

环境变量 + 各客户端配置

docs/API-NOTES.md

逆向记录:签名串、saveArticle 字段、状态码

docs/TROUBLESHOOTING.md

按症状排查

docs/FAQ.md

常见问题与能力边界

docs/CHANGELOG.md

版本变更

docs/ARCHITECTURE.md

分层、模块边界、冻结的工具面

docs/KNOWN-ISSUES.md

已修项复核、历史问题回归表、待线上验证

许可

MIT,见 LICENSE。

Available Tools

11 tools
auth_login设置 CSDN CookieA

在运行期设置/更新 CSDN Cookie(整段 Cookie 头),设置后立即对所有后续请求生效,不需要重启 MCP 进程。结构校验完全在本地完成:缺少 UserToken 或 UserName 时直接返回原因,不发任何请求。仅在首次配置或 Cookie 失效后才需要调用;只想知道当前状态请用 auth_status(不发网络请求)。它不判断 Cookie 是否被 CSDN 接受——结构合法但已经失效的 Cookie,只有后续需要登录的调用才会暴露。

Inputs: cookie (required).

auth_status查看认证状态A

报告 Cookie 是否已配置、结构是否有效以及账号名,不发任何网络请求。它不判断 Cookie 是否被 CSDN 接受(那要联网),也不知道文章状态。需要更换 Cookie 时用 auth_login,不要靠反复调用本工具排查失效——失效只有联网调用才看得出来。

Inputs: no named parameters.

delete_article删除文章A

删除一篇文章,默认进回收站(permanent=false,可在创作中心的回收站里恢复)。只有确认文章永远不该存在时才传 permanent=true——那是彻底删除,无法恢复。不要用它清理草稿以外的临时状态,也不要因为"想改标题"而删除重建:元数据直接改 update_article 就行,只有误发布的文章才必须走"删除后重建"这条路。

Inputs: article_id (required), permanent.

get_article读取文章A

按 id 读取一篇文章的完整记录(草稿也能读到),这是确认 status 原始状态码、判断草稿/审核/发布的权威口径。文章很长时传 include_content=false,只取元数据、不返回正文,避免把上下文挤爆。想浏览已发布文章列表用 list_articles;想验证一次写入是否真的生效用 verify_article。

Inputs: article_id (required), include_content.

list_articles列出文章A

列出账号的文章。scope="published"(默认)走公开接口、不需要 Cookie,只含已发布文章;scope="all" 走作者后台接口、需要 Cookie,包含草稿,并在 counts 里给出 draft/publish 等分类计数——这是唯一能回答「我有哪些草稿」的口径(公开接口看不到草稿,get_article 又要先知道 id)。注意后台接口的每页条数由 CSDN 服务端固定,page_size 传入后可能被忽略,返回的 pageSize 是实际值。state / title_contains 是本地筛选(CSDN 接口没有这两个参数):会自动多翻几页凑够匹配项(最多 5 页),返回的 total 仍是 CSDN 的总数。不要用它判断某篇文章是否发布成功——看不到不等于没发布,请用 verify_article。

Inputs: page, scope, state, page_size, +1 more.

list_categories列出文章分类A

列出可用于 publish_article / update_article 的 categories 字段的分类名。CSDN 接口不可用时会降级返回内置列表(source=builtin)而不是报错,所以拿到 builtin 时要知道那不是账号的真实分类:先确认接口可用,或直接在 CSDN 创作中心里核对分类名。它不返回分类 id,也不需要 Cookie 之外的任何参数。

Inputs: no named parameters.

list_tags列出常用标签A

列出账号常用/推荐的标签,供 publish_article 的 tags 字段(每篇最多 5 个)挑选。接口不可用时会降级返回内置列表(source=builtin),那不是账号的真实标签,只是能用的候选。它不会创建标签,也不校验标签是否存在——CSDN 允许新标签,拼错的标签会原样出现在文章上。

Inputs: no named parameters.

publish_article新建文章A

新建一篇文章并保存到 CSDN。mode 默认 draft(存草稿);显式传 mode=publish 才会公开发布,且发布后接口无法退回草稿——已发布的文章只能删除重建,所以想先审稿就保持默认。markdown 传源码(会渲染成 HTML 保存,原文同时保留);正文里指向本地文件的图片会自动上传到 CSDN 图床并替换成 CDN 地址(默认开启,upload_local_images=false 可关掉)。tags 最多 5 个;description 省略时按正文自动生成。不要用它更新已有文章(那会新建一篇),也不要传 mode=publish 来"试试能不能成功"——发布是不可逆的对外动作。

Inputs: title (required), markdown (required), mode, tags, +7 more.

update_article更新文章A

更新已有文章:只传要改的字段,未传的字段保持原值(saveArticle 会整条重写,所以未传的字段由本工具从当前记录合并回来)。已公开发布文章的线上正文(markdown)不会被接口更新:正文修改只写入草稿副本,需要在编辑器 UI 里重新发布才生效,工具会在返回里明确说明。不传 mode 时保持文章当前可见性(不会把已发布的文章退回草稿);想发布一篇草稿请显式传 mode=publish。不要用它校正正文之外的东西(那要重新发布),也不要传空字段试图"清空"某个值——省略即保持原值。

Inputs: article_id (required), mode, tags, title, +7 more.

upload_image上传图片A

把本地图片上传到 CSDN 图床,返回公网 URL(正文里请写这个绝对 URL,CSDN 有防盗链)。kind 决定通道:封面图用 cover,正文图用 body,两条通道不通用。不要用它上传非图片文件(仅支持 jpg/jpeg/png/gif/webp/bmp);也不要拿返回的 key 当图片地址用,那不是公网地址。

Inputs: kind (required), path (required).

verify_article校验文章真实状态A

回查一篇文章的真实状态:CSDN 接口的 status + 公开页的 HTTP 码,两个信号都看,缺一不可(只看接口会漏判,只看公开页会把审核中误判成失败)。expected 省略时按当前状态推断。它是只读的,不会修改任何东西;也不是必须的步骤——publish_article / update_article 已经默认自检,重复调用只会多花两次请求。

Inputs: article_id (required), expected.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 11 tools

    Disambiguation5/5

    The tools target distinct operations: authoring (publish/update), retrieval (get/list), verification, auth, metadata lookup, and image upload. Descriptions explicitly draw boundaries between similar tools such as get_article vs verify_article vs list_articles, so misselection is unlikely.

    Naming Consistency4/5

    Most names follow a consistent snake_case action_object pattern (publish_article, delete_article, list_articles, upload_image). The auth_login/auth_status pair and list_categories/list_tags remain readable and stylistically consistent, though auth_status deviates slightly from strict verb_noun naming.

    Tool Count5/5

    11 tools for a CSDN publishing integration covering article CRUD, auth, categories, tags, and image upload is well-scoped. There is no obvious bloat, and the count sits comfortably in the ideal 3-15 range.

    Completeness4/5

    Core article lifecycle is well covered, including draft/publish modes, delete with recycle/permanent options, update, list, verify, auth, metadata, and image upload. Minor gaps exist around explicitly restoring articles from recycle and setting/updating an article cover beyond uploading the image.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers