Local Docmost MCP

🚀 Docmost MCP 服务器

这是一个 MCP 服务器，可让 AI 助手通过 API 直接访问你自托管的 Docmost 文档。

它能与任何兼容 MCP 的客户端配合使用，包括：

• Claude Code / Claude Desktop
• Cursor
• Windsurf
• VS Code (GitHub Copilot)
• Cline
• Continue
• Zed

✨ 主要特性

📦 安装指南

1. 克隆仓库

git clone https://github.com/aleksvin8888/local-docmost-mcp.git
cd docmost-mcp

2. 创建虚拟环境并安装依赖

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

pip install -r requirements.txt

这将安装两个依赖项：

• mcp — 用于构建 MCP 服务器的官方 Python SDK
• requests — 用于 Docmost API 调用的 HTTP 客户端

3. 配置凭证

复制示例配置文件并填写你的详细信息：

cp config.example.json config.json

编辑 config.json：

{
  "base_url": "https://your-docmost-instance.example.com",
  "email": "your-email@example.com",
  "password": "your-password",
  "timeout": 30
}

⚠️ 重要提示

config.json 包含敏感凭证，已通过 .gitignore 排除在版本控制之外。

4. 验证设置

source venv/bin/activate   # 如果虚拟环境尚未激活

python docmost_client.py

预期输出：

=== Spaces ===
  My Space (my-space) - 019a2a69-...
  Another Space (another) - 019a5e21-...
  ...

=== Search 'example' ===
  Example Page Title - abc123def
  ...

如果你看到你的文档空间和搜索结果，说明客户端工作正常。

🚀 快速开始

连接到 MCP 客户端

服务器使用 stdio 传输协议，所有主要的 MCP 客户端都支持该协议。以下是最常用客户端的设置说明。

Claude Code

选择以下选项之一：

⚠️ 重要提示

请对 venv 中的 Python 二进制文件和 mcp_server.py 使用 绝对路径。

选项 1：全局配置（推荐）

添加到 ~/.claude/settings.json：

{
  "mcpServers": {
    "docmost": {
      "command": "/absolute/path/to/docmost-mcp/venv/bin/python",
      "args": ["/absolute/path/to/docmost-mcp/mcp_server.py"]
    }
  }
}

选项 2：项目级配置

在你的项目根目录下创建 .claude/settings.json：

{
  "mcpServers": {
    "docmost": {
      "command": "/absolute/path/to/docmost-mcp/venv/bin/python",
      "args": ["/absolute/path/to/docmost-mcp/mcp_server.py"]
    }
  }
}

选项 3：CLI 命令

claude mcp add docmost \
  -c "/absolute/path/to/docmost-mcp/venv/bin/python" \
  -- /absolute/path/to/docmost-mcp/mcp_server.py

添加配置后，重启 Claude Code 或开始新会话。

Claude Desktop

将服务器添加到你的 Claude Desktop 配置文件中：

• Linux：~/.config/claude/claude_desktop_config.json
• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "docmost": {
      "command": "/absolute/path/to/docmost-mcp/venv/bin/python",
      "args": ["/absolute/path/to/docmost-mcp/mcp_server.py"]
    }
  }
}

保存配置后重启 Claude Desktop。

Cursor / Windsurf / VS Code / 其他客户端

大多数 MCP 客户端使用相同的配置格式。添加服务器时：

• 命令：/absolute/path/to/docmost-mcp/venv/bin/python
• 参数：/absolute/path/to/docmost-mcp/mcp_server.py
• 传输协议：stdio

请参考你的客户端文档以获取确切的配置文件位置和格式。

💻 使用示例

MCP 服务器连接成功后，你的 AI 助手可以使用以下工具：

列出所有文档空间

Show me all available documentation spaces

搜索文档

Search the documentation for "user permissions"

在特定文档空间内搜索

Find "API endpoints" in the Engineering space

获取特定页面

Show me the full content of page with slug_id "abc123def"

🔧 技术细节

工作原理

1. MCP 客户端将服务器作为子进程启动，并通过 stdio（stdin/stdout）进行通信。
2. 在首次 API 调用时，服务器使用电子邮件/密码与你的 Docmost 实例进行身份验证，并从 Set-Cookie 标头接收 JWT 令牌。
3. 该令牌会被缓存到 token.json 中，以供后续请求使用。如果请求返回 401，服务器会自动重新进行身份验证并重试。
4. 页面内容在 Docmost 中以 ProseMirror JSON 形式存储。服务器在将内容返回给客户端之前，会将其转换为简洁的 Markdown（标题、列表、表格、代码块、图像、链接等）。

项目结构

docmost-mcp/
├── mcp_server.py         # MCP 服务器（3 个工具）
├── docmost_client.py     # Docmost API 客户端
├── requirements.txt      # Python 依赖项（mcp、requests）
├── config.example.json   # 配置模板
├── config.json           # 你的凭证（不在 git 中）
├── token.json            # 缓存的 JWT 令牌（自动生成，不在 git 中）
├── .gitignore
└── README.md

🔒 安全注意事项

• config.json 包含你的凭证 — 切勿将其提交到 git
• token.json 包含 JWT 令牌 — 切勿将其提交到 git
• 这两个文件已在 .gitignore 中列出

🛠️ 故障排除

"No authToken in response cookies"

• 验证 config.json 中的 email 和 password 是否正确
• 验证 base_url 是否指向你的 Docmost 实例

"Connection refused"

• 检查你的 Docmost 实例是否正在运行且可访问
• 检查你的网络连接和防火墙规则

"401 Unauthorized"

• 令牌可能已过期 — 删除 token.json，下次请求时将自动重新创建

MCP 工具未在客户端中显示

• 确保你对 venv/bin/python 和 mcp_server.py 使用了 绝对路径
• 检查虚拟环境是否安装了所有依赖项 (pip install -r requirements.txt)
• 更改配置后重启你的 MCP 客户端

📄 许可证

MIT