Docmost (self-hosted)

docmost-mcp-remote

英语 · 俄语

一个可自托管的远程 MCP 服务，适用于 Docmost Community Edition。将它部署在 Docmost 旁边， 放在你的域名后面，即可让 Claude、Claude Code、 Cursor 或 VS Code 等 AI 客户端代表每位成员读取和编辑 Wiki，使用该成员 自己的 Docmost 账户及权限。

• 一个服务、一个 Docmost、多个成员。 每位成员都在浏览器中使用自己的 Docmost 账户登录。其 AI 客户端执行的所有操作，在 Docmost 中都会以该成员的身份完成。
• 必须进行授权。 远程连接器使用 OAuth 2.1，脚本使用个人 Bearer 令牌。没有未认证模式。
• 默认安全。 read 是无需询问即可授予的唯一作用域。 写入和移至回收站需要明确授权。内容不会被永久删除，且服务会在每次更改前 保存页面正文的加密快照。
• 可自托管。 一个容器加 Postgres，并附带可直接使用的 compose.yaml。

快速入门 · 连接客户端 · 工具 · 安全模型 · 配置 · 升级

工作原理

flowchart LR
    member(["Member"]) -. "signs in once with<br/>their Docmost account" .-> server
    client["AI client<br/>Claude, Cursor, VS Code"] -- "MCP over https<br/>OAuth 2.1 or personal token" --> server["docmost-mcp-remote"]
    server -- "Docmost API,<br/>as that member" --> docmost["Docmost CE"]
    server --- db[("Postgres<br/>sessions, snapshots,<br/>audit log")]

客户端首次连接时，成员使用 Docmost 邮箱和密码登录，并选择允许客户端执行的操作。成员可以在自己的账户页面查看并撤销所有已连接的应用和令牌。

选择允许客户端执行的操作	已连接的应用和个人令牌

支持的 Docmost 版本

Docmost Community Edition 0.70.0 或更高版本。登录时会拒绝更早的版本。CI 会针对 Docmost 0.70.3、0.96.0 和 0.97.0 运行集成测试；较新的版本大多也能正常使用，并会记录警告，直到它们 被纳入测试范围。仅使用 SSO 登录的 Docmost 用户（这是 Enterprise 功能）无法使用此服务：此服务使用邮箱和密码登录。

工具

页面正文、评论和摘要会放在 <docmost-untrusted-content> 封装中返回，以便模型将其视为数据。

每次更改正文前，服务都会在自己的数据库中加密保存当前正文作为快照，保留时间为 SNAPSHOT_RETENTION_DAYS；如果无法保存快照，则不会写入任何内容。更改后，服务会重新读取页面；如果 Docmost 未应用更改，则会报告错误（当 Docmost 在 COLLAB_DISABLE_REDIS 模式下运行时会发生这种情况）。快照可能会保留后来在 Docmost 中被删除的页面内容，直到快照过期。

安全模型

成员使用自己的 Docmost 账户登录；客户端执行的所有操作都以该成员的身份进行，并遵循其 Docmost 权限。服务会使用从 SECRET_KEY 派生的密钥加密存储 Docmost 会话令牌；除非设置了 RELOGIN_MODE=stored_password，否则不会存储密码。个人令牌以哈希形式存储，且只显示一次。登录页面启用了 CSRF 防护，并设有按 IP 和电子邮件地址限制的速率限制。

此服务本身是 OAuth 2.1 授权服务器，遵循 MCP 授权规范：动态客户端注册（按 IP 限制注册数量，重定向 URI 必须是 https、环回 http 或原生应用 scheme）、使用 PKCE 的授权码（仅支持 S256）、精确匹配重定向 URI、令牌绑定到此服务的 /mcp 资源、访问令牌有效期为一小时，以及每次使用都会轮换的 30 天刷新令牌。重用刷新令牌或重放授权码会撤销整个授权。OAuth 授权和个人令牌会在同一个账户页面中列出并可撤销。

页面内容会被视为不可信数据，并标记为此类内容，供模型识别。页面中的提示词注入仍可能导致客户端在成员授予的权限范围内采取行动，因此仅向你信任的客户端授予 write 和 delete 权限。工具调用会按成员进行限制，并记录在审计日志中。关于如何报告漏洞，请参阅威胁模型、SECURITY.md，以及设计文档。

快速开始

你需要安装 Docker 和 Compose、服务器可以访问的 Docmost，以及一个启用了 https 的服务器主机名，例如 mcp.example.com。

1. 下载 compose 文件和设置模板：

   mkdir docmost-mcp && cd docmost-mcp
   curl -fsSLO https://raw.githubusercontent.com/bbik52/docmost-mcp-remote/master/compose.yaml
   curl -fsSL -o .env https://raw.githubusercontent.com/bbik52/docmost-mcp-remote/master/.env.example
   

2. 编辑 .env：设置 PUBLIC_URL（此服务器的 https URL）、DOCMOST_URL、一个足够长的随机 POSTGRES_PASSWORD 和 SECRET_KEY（openssl rand -hex 32 可为两者生成合适的值）。可以设置 ALLOWED_EMAILS 来限制可登录的用户。

3. 启动服务并检查它是否已运行：

   docker compose up -d
   curl http://127.0.0.1:8000/healthz
   

4. 在 127.0.0.1:8000 前配置一个支持 https 的反向代理（见下文），然后在浏览器中打开 PUBLIC_URL/login，检查能否使用你的 Docmost 账号登录。

5. 连接客户端（见连接客户端）。

服务器会在启动时应用数据库迁移。请像备份 Docmost 一样备份 Postgres 卷：其中存储着加密会话、快照和审计日志。丢失 SECRET_KEY 会导致所有成员退出登录，并使快照无法读取。

# docmost-mcp-remote: the server and its Postgres.
# Copy .env.example to .env and fill in the required values first, then put a
# reverse proxy with https in front of port 8000.

services:
  server:
    # "1" follows 1.x releases; set IMAGE_TAG to a full version such as 1.0.0 to pin one.
    image: ghcr.io/bbik52/docmost-mcp-remote:${IMAGE_TAG:-1}
    restart: unless-stopped
    environment:
      PUBLIC_URL: ${PUBLIC_URL:?set PUBLIC_URL to the public https URL of this server}
      DOCMOST_URL: ${DOCMOST_URL:?set DOCMOST_URL to the base URL of your Docmost}
      DOCMOST_ALLOW_INSECURE_HTTP: ${DOCMOST_ALLOW_INSECURE_HTTP:-false}
      DATABASE_URL: postgresql://docmost_mcp:${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD}@postgres:5432/docmost_mcp
      SECRET_KEY: ${SECRET_KEY:?set SECRET_KEY to a random value of at least 32 characters}
      SECRET_KEY_PREVIOUS: ${SECRET_KEY_PREVIOUS:-}
      ALLOWED_EMAILS: ${ALLOWED_EMAILS:-}
      ALLOWED_SPACES: ${ALLOWED_SPACES:-}
      RELOGIN_MODE: ${RELOGIN_MODE:-ask}
      SNAPSHOT_RETENTION_DAYS: ${SNAPSHOT_RETENTION_DAYS:-30}
      AUDIT_RETENTION_DAYS: ${AUDIT_RETENTION_DAYS:-90}
      TOOL_CALLS_PER_MINUTE: ${TOOL_CALLS_PER_MINUTE:-60}
      MAX_PAGE_CHARS: ${MAX_PAGE_CHARS:-60000}
      # The port is published on 127.0.0.1 only, so every client is a local proxy.
      FORWARDED_ALLOW_IPS: ${FORWARDED_ALLOW_IPS:-*}
      LOG_LEVEL: ${LOG_LEVEL:-info}
    ports:
      - "127.0.0.1:8000:8000"
    depends_on:
      postgres:
        condition: service_healthy
    read_only: true
    tmpfs:
      - /tmp
    cap_drop:
      - ALL
    security_opt:
      - no-new-privileges:true

  postgres:
    image: postgres:17-alpine
    restart: unless-stopped
    environment:
      POSTGRES_USER: docmost_mcp
      POSTGRES_DB: docmost_mcp
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD}
    volumes:
      - postgres-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U docmost_mcp -d docmost_mcp"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  postgres-data:

对于不使用容器的配置，也可以从 PyPI 获取服务器（pip install docmost-mcp-remote 或 uvx docmost-mcp-remote）；它需要 Postgres，并使用相同的环境变量设置。

反向代理

服务器通过普通 http 进行监听，并要求由反向代理终止 https。请在其专属主机名的根路径下提供服务；不支持子路径。代理不得缓冲响应，因为 MCP 会以流的形式传输数据。

Caddy（会自动获取证书）：

mcp.example.com {
    reverse_proxy 127.0.0.1:8000
}

server {
    listen 443 ssl;
    server_name mcp.example.com;
    ssl_certificate     /etc/letsencrypt/live/mcp.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/mcp.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_buffering off;
        proxy_read_timeout 1h;
    }
}

服务器使用 X-Forwarded-For 执行基于 IP 的速率限制。compose 文件仅在 127.0.0.1 上发布端口，并信任来自所有客户端的此标头；如果你在其他地址发布端口，请将 FORWARDED_ALLOW_IPS 设置为代理的地址。

连接客户端

MCP 端点为 PUBLIC_URL/mcp，例如 https://mcp.example.com/mcp。支持 MCP 授权的客户端会打开浏览器窗口：使用你的 Docmost 邮箱和密码登录，然后选择允许客户端执行的操作。始终会授予 read 权限；只有在信任客户端时才勾选 write 或 delete。

Claude.ai 和 Claude Desktop：依次选择 Settings、Connectors、Add custom connector，然后输入端点 URL。对于 Claude.ai，服务器必须可通过互联网以 https 访问。

Claude Code：

claude mcp add --transport http docmost https://mcp.example.com/mcp

然后在 Claude Code 中运行 /mcp 以登录。

Cursor（~/.cursor/mcp.json）：

{
  "mcpServers": {
    "docmost": { "url": "https://mcp.example.com/mcp" }
  }
}

VS Code（.vscode/mcp.json）：

{
  "servers": {
    "docmost": { "type": "http", "url": "https://mcp.example.com/mcp" }
  }
}

使用个人令牌（适用于脚本和不支持 OAuth 的客户端）：

1. 打开 PUBLIC_URL/login，使用你的 Docmost 邮箱和密码登录。

2. 在账号页面创建一个具有所需权限范围的个人令牌。

3. 使用端点和标头 Authorization: Bearer <token> 配置客户端：

   claude mcp add --transport http docmost https://mcp.example.com/mcp \
     --header "Authorization: Bearer dmr_..."
   

已连接的应用和令牌会列在账号页面 PUBLIC_URL/account 上，也可以在那里撤销。

管理

admin 命令需在服务器运行的环境中执行，并使用相同的环境变量：

docker compose exec server docmost-mcp-remote admin members
docker compose exec server docmost-mcp-remote admin migrate
docker compose exec server docmost-mcp-remote admin grants [email protected]
docker compose exec server docmost-mcp-remote admin revoke-grant <grant id>
docker compose exec server docmost-mcp-remote admin revoke-member [email protected]
docker compose exec server docmost-mcp-remote admin disable-member [email protected]
docker compose exec server docmost-mcp-remote admin audit --email [email protected]

revoke-member 会撤销该成员的所有授权并删除其存储的 Docmost 会话；disable-member 会将其封锁，直到执行 enable-member。每次工具调用都会记录在审计日志中，包含工具、页面或空间 ID 以及结果，但不记录内容或参数。

轮换 SECRET_KEY：将旧值设为 SECRET_KEY_PREVIOUS，设置新的 SECRET_KEY，重启，然后运行 admin rotate-key；之后移除 SECRET_KEY_PREVIOUS 并再次重启。

升级

1. 阅读 更新日志 中的“升级说明”。

2. 备份数据库：

   docker compose exec -T postgres pg_dump -U docmost_mcp -Fc docmost_mcp > docmost-mcp-$(date +%F).dump
   

3. 拉取新镜像并重启：

   docker compose pull && docker compose up -d
   

服务器会在启动时升级数据库架构，每次在一个事务中由一个进程执行，因此升级失败时会保留旧架构。 docker compose exec server docmost-mcp-remote admin migrate 可显示架构修订版本。

镜像标签 1 跟随 1.x 版本发布；如需固定版本，请在 .env 中设置 IMAGE_TAG。架构升级后，不支持回退到较旧版本：较旧的服务器无法在较新的架构上启动。如需回滚，请使用旧镜像恢复备份：

docker compose stop server
docker compose exec -T postgres pg_restore -U docmost_mcp -d docmost_mcp --clean --if-exists < docmost-mcp-2026-01-31.dump
IMAGE_TAG=1.0.0 docker compose up -d

配置

开发

uv sync
uv run ruff check . && uv run ruff format --check .
uv run mypy
DATABASE_TEST_URL=postgresql://test:test@localhost:5433/test uv run pytest

未设置 DATABASE_TEST_URL 时，会跳过需要 Postgres 的测试；例如： docker run -d -p 5433:5432 -e POSTGRES_USER=test -e POSTGRES_PASSWORD=test postgres:17-alpine。

集成测试会连接实际运行的 Docmost：

DOCMOST_VERSION=0.97.0 docker compose -f tests/integration/compose.yaml up -d
DOCMOST_TEST_URL=http://localhost:3000 uv run pytest tests/integration

使用本地构建运行 compose 服务栈：

docker build -t ghcr.io/bbik52/docmost-mcp-remote:dev .
IMAGE_TAG=dev docker compose up -d

请参阅 CONTRIBUTING.md 和路线图。

许可证

Apache License 2.0。许可证不涵盖项目名称：欢迎使用其他名称创建分支。本项目为独立实现，与 Docmost 无关联。其灵感来源于 docmost-mcp-oss。