Docmost (self-hosted)

docmost-mcp-remote

英語 · ロシア語

Docmost コミュニティエディション向けの、セルフホスト可能なリモートMCPサーバーです。Docmost のそばで実行し、独自ドメインの背後に配置すると、Claude、Claude Code、Cursor、VS Code などの AI クライアントが、各メンバー本人の Docmost アカウントと権限で、メンバーに代わって Wiki を読み書きできます。

• 1 つのサーバー、1 つの Docmost、多数のメンバー。 各メンバーはブラウザーで自分の Docmost アカウントにサインインします。AI クライアントが行うすべての操作は、Docmost ではそのメンバー本人の操作として実行されます。
• 認証は必須です。 リモートコネクターには OAuth 2.1、スクリプトには個人用ベアラートークンを使用します。認証なしでの利用モードはありません。
• デフォルトで安全です。 確認なしで付与されるスコープは read のみです。書き込みとゴミ箱への移動には、明示的なスコープが必要です。完全に削除されることはなく、サーバーは変更のたびにページ本文の暗号化されたスナップショットを保存します。
• セルフホスト可能です。 Postgres と 1 つのコンテナで構成でき、すぐに使える 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 コミュニティエディション 0.70.0 以降。古いバージョンはサインイン時に拒否されます。CI では Docmost 0.70.3、0.96.0、0.97.0 を対象に統合テストを実行します。それ以降のリリースもほとんどの場合動作し、テスト済みの範囲に追加されるまでは警告がログに記録されます。SSO のみでサインインする Docmost ユーザーは、このサーバーを利用できません（SSO はエンタープライズ機能です）。このサーバーはメールアドレスとパスワードを使ってサインインします。

ツール

ページ本文、コメント、スニペットは、モデルがデータとして扱うよう <docmost-untrusted-content> エンベロープ内に返されます。

本文を変更する前に、サーバーは現在の本文を暗号化して自身のデータベースにスナップショットとして保存し、 SNAPSHOT_RETENTION_DAYS の期間保持します。スナップショットを保存できない場合、書き込みは行われません。変更後はページを再取得し、Docmost に変更が適用されていなければエラーを報告します（これは Docmost が COLLAB_DISABLE_REDIS を設定して実行されている場合に発生します）。スナップショットには、Docmost で後から削除されたページの内容が、有効期限まで残る場合があります。

セキュリティモデル

メンバーは各自の Docmost アカウントでサインインします。クライアントのすべての操作は、そのメンバーとして、そのメンバーの Docmost 権限で実行されます。サーバーは SECRET_KEY から導出したキーを使って Docmost のセッショントークンを暗号化して保存し、RELOGIN_MODE=stored_password の場合を除き、パスワードは保存しません。個人用トークンはハッシュとして保存され、一度だけ表示されます。サインインページには CSRF 保護と、IP アドレスごとおよびメールアドレスごとのレート制限があります。

このサーバーは、MCP 認可仕様に準拠した独自の OAuth 2.1 認可サーバーです。動的クライアント登録（IP アドレスごとに制限。リダイレクト URI には https、ループバックの http、またはネイティブアプリのスキームが必要）、PKCE を使用した認可コード（S256 のみ）、リダイレクト URI の完全一致、このサーバーの /mcp リソースにバインドされたトークン、有効期間 1 時間のアクセストークン、および使用のたびにローテーションされる有効期間 30 日のリフレッシュトークンに対応しています。リフレッシュトークンの再使用、または認可コードのリプレイがあった場合、許可全体が取り消されます。OAuth の許可と個人用トークンは、同じアカウントページで一覧表示および取り消しができます。

ページの内容は信頼できないデータとして扱われ、モデルにもそのようにラベル付けされます。ページ内のプロンプトインジェクションによって、クライアントがメンバーから付与されたスコープの範囲内で動作する可能性はあるため、信頼できるクライアントにのみ write と delete を許可してください。ツール呼び出しはメンバーごとに制限され、監査ログに記録されます。脆弱性の報告方法については、脅威モデル、SECURITY.md を参照してください。また、設計もご覧ください。

クイックスタート

Compose を使える Docker、サーバーからアクセス可能な 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;
    }
}

サーバーは、IP ごとのレート制限に X-Forwarded-For を使用します。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：設定、コネクター、カスタムコネクターを追加の順に進み、エンドポイント 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
   

サーバーは起動時に、1つのトランザクション内で、一度に1つのプロセスだけがデータベーススキーマをアップグレードします。そのため、アップグレードに失敗しても古いスキーマは維持されます。 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

Postgres が必要なテストは、DATABASE_TEST_URL が設定されていない場合はスキップされます。たとえば、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に着想を得ています。