404K Knowledge Planet MCP Server

License: MIT

通过 Model Context Protocol（MCP）让 Claude Desktop、Codex、Cursor 和其他 MCP 客户端读取 404k.wlhtea.xyz 上的私有知识星球归档。

MCP Server 不持有知识星球 Cookie，也不直接访问知识星球。它只使用独立的 API Token 请求：

https://404k.wlhtea.xyz/api/v1

功能

查看最近同步状态和当前话题数量；
分页浏览历史话题；
搜索标题、正文和标签，并排除指定关键词；
精确匹配一个或多个标签，支持任一/全部匹配；
排除指定标签；
按北京时间今天、最近 24 小时、3 天、7 天或自定义日期筛选；
独立组合精华、图片和附件条件；
按最新、最早、阅读量或点赞量排序；
按话题 ID 获取完整正文；
返回本站受保护的图片、PDF 和附件地址；
所有请求通过 Authorization: Bearer 鉴权。

提供的工具（当前版本 1.1.0）：

zsxq_status
zsxq_list_topics
zsxq_search_topics
zsxq_get_topic

安装

要求 Node.js 20 或更高版本。

从 GitHub 安装：

git clone https://github.com/wlhtea/zsxq-mcp-server.git
cd zsxq-mcp-server
npm ci
npm link

从发布的 .tgz 安装：

npm install -g ./wlhtea-zsxq-mcp-server-1.1.0.tgz

本仓库内直接运行：

cd mcp-server
npm ci
ZSXQ_API_TOKEN="YOUR_API_TOKEN" npm start

环境变量

名称	必填	默认值	说明
`ZSXQ_API_TOKEN`	是	无	朋友专用 API Token
`ZSXQ_API_BASE_URL`	否	`https://404k.wlhtea.xyz`	数据 API 所在网站
`ZSXQ_API_TIMEOUT_MS`	否	`30000`	单次请求超时

不要把真实 Token 提交到 Git；.env.example 只保留占位符。

Claude Desktop 配置

{
  "mcpServers": {
    "zsxq-404k": {
      "command": "node",
      "args": ["/ABSOLUTE_PATH/zsxq-mcp-server/src/index.js"],
      "env": {
        "ZSXQ_API_BASE_URL": "https://404k.wlhtea.xyz",
        "ZSXQ_API_TOKEN": "YOUR_API_TOKEN"
      }
    }
  }
}

Codex 配置

安装后可以直接注册到 Codex：

codex mcp add zsxq-404k \
  --env ZSXQ_API_BASE_URL=https://404k.wlhtea.xyz \
  --env ZSXQ_API_TOKEN=YOUR_API_TOKEN \
  -- zsxq-mcp-server

也可以在 ~/.codex/config.toml 中添加：

[mcp_servers.zsxq-404k]
command = "node"
args = ["/ABSOLUTE_PATH/zsxq-mcp-server/src/index.js"]

[mcp_servers.zsxq-404k.env]
ZSXQ_API_BASE_URL = "https://404k.wlhtea.xyz"
ZSXQ_API_TOKEN = "YOUR_API_TOKEN"

验证：

codex mcp get zsxq-404k
codex mcp list

API 调试

curl 'https://404k.wlhtea.xyz/api/v1/status' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

curl 'https://404k.wlhtea.xyz/api/v1/topics?offset=0&limit=20' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

curl 'https://404k.wlhtea.xyz/api/v1/topics?q=AI&limit=20' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

curl --get 'https://404k.wlhtea.xyz/api/v1/topics' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  --data-urlencode 'q=AI' \
  --data-urlencode 'tag=大模型' \
  --data-urlencode 'tag=算力' \
  --data-urlencode 'tagMode=all' \
  --data-urlencode 'excludeTag=广告' \
  --data-urlencode 'timeRange=7d' \
  --data-urlencode 'hasFiles=true' \
  --data-urlencode 'sort=readers' \
  --data-urlencode 'limit=20'

搜索和筛选

zsxq_search_topics 接受以下参数；除 query 外，其余参数也可用于 zsxq_list_topics：

参数	类型	默认值	说明
`query`	string	必填	搜索标题、正文和标签
`excludeQuery`	string	无	排除搜索文本中包含该关键词的话题
`tags`	string[]	`[]`	精确标签，最多 20 个
`tagMode`	`any \| all`	`any`	多标签匹配任意一个或全部
`excludeTags`	string[]	`[]`	命中任一精确标签即排除
`timeRange`	`all \| today \| 24h \| 3d \| 7d`	`all`	北京时间今天或滚动时间窗口
`startDate`	string	无	`YYYY-MM-DD` 或带时区 ISO 8601 时间
`endDate`	string	无	日期格式包含北京时间当天
`filter`	`all \| digest \| image \| file \| image_and_file`	`all`	兼容的快捷类型筛选
`digested`	boolean	无	可与图片、附件条件组合
`hasImages`	boolean	无	要求包含或不包含图片
`hasFiles`	boolean	无	要求包含或不包含 PDF/附件
`sort`	`newest \| oldest \| readers \| likes`	`newest`	排序方式
`offset`	integer	`0`	分页偏移
`limit`	integer	`20`	返回数量，最大 50

startDate 和 endDate 会覆盖 timeRange 对应的同侧边界。日期值 YYYY-MM-DD 按 Asia/Shanghai 解释；endDate 会包含当天 23:59:59.999。

示例自然语言请求：

搜索近 7 天标签同时包含“大模型”和“算力”、带附件的内容，按阅读量排序。
搜索“英伟达”，排除“广告”标签和“推广”关键词，只看精华且同时有图片和附件。
列出 2026-07-01 到 2026-07-31 的半导体标签内容，按最早时间排序。

OpenAPI 3.1 文档：

https://404k.wlhtea.xyz/api/v1/openapi.json

OpenAPI 文档本身也需要相同的 Bearer Token。

测试

npm test

License

MIT

Security

MCP Server 只需要 ZSXQ_API_TOKEN，不需要也不接受知识星球 Cookie。不要把真实 Token 提交到 Git、Issue、日志或截图中，详见 SECURITY.md。