docmost-mcp

一个 MCP 服务器，通过常规 REST API 为 AI 代理提供对自托管 Docmost wiki 的读写访问权限。

为什么存在

Docmost 自带 MCP 端点，但受付费许可证限制——设置界面在 API 管理处显示 “需付费许可证”，并且在社区版上 /api/mcp 返回 404。生成 API 密钥也受到同样的限制。

不过，社区版的普通 REST API 是完全开放的。本服务器只是它的一个轻量封装：操作相同，只是用会话认证代替 API 密钥。

Related MCP server: MediaWiki MCP Server

要求

• Python 3.11+

• 一个可通过 HTTP(S) 访问的 Docmost 实例

• 为代理准备一个专用的 Docmost 用户账户

安装

git clone https://github.com/<you>/docmost-mcp.git
cd docmost-mcp
python3 -m venv venv
./venv/bin/pip install -r requirements.txt

配置

复制示例配置并填写：

cp config.example.json config.json
chmod 600 config.json

{
  "url": "https://docmost.example.com",
  "api_key": "",
  "email": "agent@example.com",
  "password": "..."
}

支持两种认证模式：

如果设置了 api_key，则优先使用；否则使用凭据。

可以通过 DOCMOST_MCP_CONFIG 环境变量覆盖配置路径。

创建专用账户

不要使用工作区所有者的凭据。邀请一个单独的用户（设置 → 成员 → 邀请），并仅授予其代理所需空间的访问权限。Docmost 中的空间访问权限通常继承自默认的 Everyone（所有人）组，因此在假设代理受到限制之前，请先检查该组可以访问哪些内容。

如果你不想创建第二个邮箱，Gmail 风格的加号地址（you+agent@gmail.com）也可以使用。

验证

selftest.py 会测试整个链路——登录、读取、写入、回读、删除：

./venv/bin/python selftest.py

连接代理

服务器通过 stdio 使用 MCP 协议通信。

Claude Code

claude mcp add docmost -- /path/to/docmost-mcp/venv/bin/python /path/to/docmost-mcp/server.py

或者手动将其添加到 ~/.claude.json：

{
  "mcpServers": {
    "docmost": {
      "type": "stdio",
      "command": "/path/to/docmost-mcp/venv/bin/python",
      "args": ["/path/to/docmost-mcp/server.py"],
      "env": {}
    }
  }
}

之后重启 Claude Code——配置在启动时读取。

Claude Desktop

将同样的配置块添加到 claude_desktop_config.json：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json

• Windows：%APPDATA%\Claude\claude_desktop_config.json

Cursor

使用相同的 mcpServers 结构，将其添加到项目中的 .cursor/mcp.json，或全局的 ~/.cursor/mcp.json。

任何其他 MCP 客户端

使用虚拟环境的 Python 启动 server.py，并通过 stdin 和 stdout 进行 JSON-RPC 通信。一个最小握手示例：

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"probe","version":"1"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/list"}

一个便捷包装器可以缩短命令：

#!/bin/sh
exec /path/to/docmost-mcp/venv/bin/python /path/to/docmost-mcp/server.py "$@"

工具

fmt 为 markdown（默认）、html 或 json。

关于 Docmost API 的说明

如果你扩展此服务器，以下几点值得了解：

• 每个端点都是 POST，包括读取操作。

• /pages/create 和 /pages/update 要求包含 format 字段（json | markdown | html）。省略该字段会返回 400。

• 响应将负载包装在 {"data": ...} 中；客户端会将其解包。

• 在社区版上，/api/api-keys 返回 200 和一个空列表——列出密钥是开放的，只有密钥创建受许可证限制。

• 端点路径和负载结构取自 Docmost 客户端源码（apps/client/src/features/*/services/*.ts），并非猜测。

安全

• config.json 包含明文密码。请将其权限设为 600，并排除在版本控制之外——它已在 .gitignore 中。

• 为代理账户授予能完成工作所需的最小空间访问权限。

• 该账户的操作会以它自己的名义显示在 Docmost 中，因此页面历史记录始终可追溯。

兼容性

基于 Docmost 0.95.0 和 Python MCP SDK 2.0 构建。请注意，SDK 2.0 将 FastMCP 重命名为 MCPServer，并将其移至 mcp.server；2.0 之前的导入路径 mcp.server.fastmcp 将无法使用。

许可证

MIT — 参见 LICENSE。

本项目与 Docmost 无关联。