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