Docmost (self-hosted)

Run it next to your Docmost, put it behind your domain, and connect Claude, Claude Code, Cursor, VS Code or any other MCP client. Every member signs in with their own Docmost account, so the assistant sees exactly what they can see and every change in Docmost carries their name.

Independent community project, not affiliated with or endorsed by Docmost, Inc. Docmost is a trademark of Docmost, Inc.; the name is used only to say which software this server works with.

✨ Highlights

• 👥 One server for the whole team. Each member signs in once in the browser with their own Docmost account. Everything their AI client does is done as them, with their Docmost rights.
• 🔐 Real authorization. OAuth 2.1 for remote connectors (Claude.ai, Claude Desktop, Claude Code, Cursor, VS Code) and personal tokens for scripts. There is no unauthenticated mode.
• 🛡️ Safe by default. Only read is granted without asking; write, delete and admin are opt-in per client. Nothing is deleted permanently, risky changes ask you first, and an encrypted snapshot of a page is saved before every change.
• 🧰 62 tools. Read, search, write by section, comment with @-mentions, move, label, export, restore old versions, check a space's health and run the workspace: spaces, groups, invitations and roles.
• 📎 Files without burning tokens. The assistant gives you an upload link: drop files in the browser, put them in order, and they land in the right place of the page.
• 🐳 Easy to host. One container plus Postgres with a ready compose.yaml, or pip install. Tested in CI against Docmost 0.80.1 to 0.97.

⭐ If this server is useful to you, please star the repository. It helps other Docmost users find it and tells us the work is worth continuing.

🆚 How it compares

There are several open-source MCP servers for Docmost Community Edition. Most of them run on one person's machine with one shared Docmost account. This one is built to be shared by a team.

Based on the public Docmost CE MCP servers we could find in October 2026. They are good choices for a single person working locally over stdio, and some offer things this server does not, such as permanent deletion.

🧭 How it works

[A member uses an AI client, which talks MCP over https with OAuth 2.1 or a personal token to docmost-mcp-remote. The member signs in once with their own Docmost account. The server calls the Docmost API as that member and keeps encrypted sessions, snapshots and the audit log in Postgres.]

The first time a client connects, the member signs in with their Docmost email and password and picks what the client may do. They can see and revoke every connected app and token on their account page.

🚀 Quick start

You need Docker with Compose, a Docmost reachable from the server, and a host name with https for the server itself, for example mcp.example.com.

1. Download the compose file and the settings template:

   sh

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

2. Edit .env: set PUBLIC_URL (the https URL of this server), DOCMOST_URL, a long random POSTGRES_PASSWORD and SECRET_KEY (openssl rand -hex 32 gives a good value for both). Consider ALLOWED_EMAILS to limit who can sign in.

3. Start it and check that it is up:

   sh

   docker compose up -dcurl http://127.0.0.1:8000/healthz

4. Put a reverse proxy with https in front of 127.0.0.1:8000 (see Reverse proxy) and open PUBLIC_URL/login in a browser to check that you can sign in with your Docmost account.

5. Connect a client (see Connecting a client).

The server applies its database migrations at startup. Back up the Postgres volume like you back up Docmost: it holds the encrypted sessions, the snapshots and the audit log. Losing SECRET_KEY signs every member out and makes the snapshots unreadable.

# 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.1.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}      UPLOAD_RETENTION_MINUTES: ${UPLOAD_RETENTION_MINUTES:-60}      UPLOAD_MAX_MB: ${UPLOAD_MAX_MB:-50}      TOOL_CALLS_PER_MINUTE: ${TOOL_CALLS_PER_MINUTE:-60}      MAX_PAGE_CHARS: ${MAX_PAGE_CHARS:-60000}      # Proxies on loopback or a private network; the client address is the last      # untrusted one in X-Forwarded-For, so a header sent by the client is ignored.      FORWARDED_ALLOW_IPS: ${FORWARDED_ALLOW_IPS:-127.0.0.1,::1,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,fc00::/7}      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:

The server is also on PyPI (pip install docmost-mcp-remote or uvx docmost-mcp-remote) for setups without containers; it needs Postgres and the same settings as environment variables.

Reverse proxy

The server listens on plain http and expects a reverse proxy that terminates https. Serve it at the root of its own host name; a sub-path is not supported. The proxy must not buffer responses, because MCP streams them.

Caddy (gets certificates by itself):

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 $remote_addr;        proxy_set_header X-Forwarded-Proto $scheme;        proxy_buffering off;        proxy_read_timeout 1h;    }}

The server uses X-Forwarded-For for its per-IP rate limits. The proxy must set the header to the address it sees, not pass on what the client sent: the nginx example above does that with $remote_addr, and Caddy and Traefik do it by default. The compose file trusts proxies on loopback and private networks (FORWARDED_ALLOW_IPS); if your proxy reaches the server from a public address, set it to that address.

🔌 Connecting a client

The MCP endpoint is PUBLIC_URL/mcp, for example https://mcp.example.com/mcp. Clients that support MCP authorization open a browser window: sign in with your Docmost email and password and choose what the client may do. read is always granted; tick write, delete or admin only for clients you trust.

Give clients the full endpoint, ending in /mcp. The server's base URL alone is refused with invalid_target. After "Allow" a page sends you back to the app; if the browser asks whether to open a desktop app such as Cursor, allow it, or use the link on the page.

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

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

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

Connected apps and tokens are listed and revoked on the account page, PUBLIC_URL/account.

🧰 Tools

62 tools in groups. The scope is what a client needs to be granted to see the tool: read is always granted, the others are opt-in.

Account and spaces

Browsing and reading pages

Search

Writing pages

Comments

History, snapshots and restore

Labels and links

Files and export

Trash

People and groups

Space administration

Workspace administration

People cannot be removed from the workspace or from groups, and groups cannot be deleted. Docmost has no way to create an account or edit someone else's profile: people join through an invitation and set their own password.

🛡️ Safety nets

• Snapshots. Before every body change the server saves the current body as a snapshot in its own database, encrypted, for SNAPSHOT_RETENTION_DAYS; if the snapshot cannot be saved, nothing is written. Snapshots can hold content of pages that were later deleted in Docmost until they expire.
• Read-back. After a change the server reads the page back and reports an error if Docmost did not apply it (this happens when Docmost runs with COLLAB_DISABLE_REDIS).
• Confirmation. Risky changes ask you first, in your client, where the client supports it (MCP elicitation): moving a page to the Trash, moving or copying a page to another space, giving people or groups a role in a space, inviting people, changing a workspace role and deactivating someone. The question goes to you, not to the model, so text in a page cannot answer it. If the client says it can ask but the question fails, nothing changes. Clients that cannot ask make these changes without the question, within the scopes you granted.
• Busy pages. A change that rewrites the whole body (a replace, a section, a JSON write, a restore) is refused while someone else is editing the page, that is when another person saved it in the last minute, because their typing would be lost. Appending and prepending merge with their edits and are not refused.
• Untrusted content. Page bodies, comments and snippets are returned inside a <docmost-untrusted-content> envelope so the model treats them as data.

📎 Adding files

Passing a file to the model costs tokens: as base64, about a million per megabyte. So create_upload_link gives a one-time link to a page instead. The person opens it, drops in one or more files (or picks them), puts them in order and presses Done; the files appear in the page at the end, at the end of a section (after_heading) or after a paragraph (after_text). An assistant that can run commands sends files it has with curl to the same link. Until Done the files are kept on this server, encrypted; the link works for UPLOAD_RETENTION_MINUTES and whatever was not added by then is deleted. upload_attachment takes the same place parameters.

[The upload page: a drop area, three images and a PDF with arrows to reorder them, and a Done button]

💬 Resources and prompts

Besides tools, which the model picks itself, the server offers resources and prompts that you pick in your client, where the client supports them (Claude Desktop and Claude Code do; many clients only support tools).

A prompt only writes the request; the model does the work with the tools the connection is allowed to use. Resource reads count against TOOL_CALLS_PER_MINUTE and go to the audit log as read_resource.

📦 Supported Docmost versions

Docmost Community Edition 0.80.1 or newer. Older versions are refused at sign-in and on every tool call: they have published security advisories that the endpoints this server calls expose (CVE-2026-34212, fixed in 0.71.0, and CVE-2026-48073, fixed in 0.80.1). CI runs the integration tests against Docmost 0.80.1, 0.96.0 and 0.97.0; newer releases work in most cases and log a warning until they are added to the tested range. Docmost users who sign in with SSO only (an Enterprise feature) cannot use this server: it signs in with email and password. Labels and backlinks need Docmost 0.90 or newer, and the title_only and labels search filters and list_attachments need 0.96 or newer; on older versions these tools answer that Docmost needs an upgrade.

🔐 Security model

Members sign in with their own Docmost account; everything a client does is done as that member, with their Docmost rights. The server keeps the Docmost session token encrypted with a key derived from SECRET_KEY and does not store passwords unless RELOGIN_MODE=stored_password. Personal tokens are stored as hashes, shown once and expire after 90 days by default. The sign-in page has CSRF protection and per-IP and per-email rate limits, and "Sign out everywhere" on the account page ends its sessions in every browser.

The server is its own OAuth 2.1 authorization server, following the MCP authorization spec: dynamic client registration (limited per IP, redirect URIs must be https, loopback http or a native app scheme), authorization code with PKCE (S256 only), exact redirect URI match, tokens bound to this server's /mcp resource, one-hour access tokens and 30-day refresh tokens that rotate on every use. A reused refresh token or a replayed code revokes the whole grant. OAuth grants and personal tokens are listed and revoked on the same account page.

Page content is treated as untrusted data and labelled as such for the model; titles and names, which are returned as plain fields, lose hidden and control characters and are cut at 300 characters. Prompt injection in a page can still make a client act within the scopes the member granted, so grant write, delete and admin only to clients you trust. Tool calls and resource reads are limited per member and recorded in an audit log.

Exports of several pages and file downloads are handed out as links to this server that are valid for ten minutes. A link carries, encrypted, who asked and what to download, so anyone holding it can download the file until it expires; the server streams the file from Docmost with that member's session and stores nothing. Links are kept out of the access log.

See the threat model, SECURITY.md for how to report a vulnerability and the design.

🛠️ Administration

The admin command runs where the server runs, with the same environment:

docker compose exec server docmost-mcp-remote admin membersdocker compose exec server docmost-mcp-remote admin migratedocker 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 revokes every grant of the member and drops their stored Docmost session; disable-member blocks them until enable-member. Every tool call and resource read is recorded in the audit log with the tool, the page or space id and the outcome, never with content or arguments.

To rotate SECRET_KEY: set the old value as SECRET_KEY_PREVIOUS and a new SECRET_KEY, restart, run admin rotate-key, then remove SECRET_KEY_PREVIOUS and restart again.

⬆️ Upgrading

1. Read the changelog for "Upgrade notes".

2. Back up the database:

   sh

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

3. Pull the new image and restart:

   sh

   docker compose pull && docker compose up -d

The server upgrades its database schema at startup, in one transaction and one process at a time, so a failed upgrade leaves the old schema in place. docker compose exec server docmost-mcp-remote admin migrate shows the schema revision.

The image tag 1 follows 1.x releases; set IMAGE_TAG in .env to pin a version. Going back to an older version after its schema was upgraded is not supported: an older server refuses to start on a newer schema. To roll back, restore the backup with the old image:

docker compose stop serverdocker compose exec -T postgres pg_restore -U docmost_mcp -d docmost_mcp --clean --if-exists < docmost-mcp-2026-01-31.dumpIMAGE_TAG=1.1.0 docker compose up -d

⚙️ Configuration

🧑‍💻 Development

uv syncuv run ruff check . && uv run ruff format --check .uv run mypyDATABASE_TEST_URL=postgresql://test:test@localhost:5433/test uv run pytest

Tests that need Postgres are skipped without DATABASE_TEST_URL; for example docker run -d -p 5433:5432 -e POSTGRES_USER=test -e POSTGRES_PASSWORD=test postgres:17-alpine.

Integration tests run against a real Docmost:

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

To run the compose stack with a local build:

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

docmost-mcp-remote --tool-catalog serves the tools, resources and prompts over stdio without Docmost, a database or any configuration, and refuses every call. MCP directories use it to list what the server offers, for example docker run -i --rm ghcr.io/bbik52/docmost-mcp-remote --tool-catalog.

See CONTRIBUTING.md and the roadmap.

🙌 Feedback and support

⭐ Like it? Star the repository. Stars help other Docmost teams find the server and keep the project going.

Issues are not only for bugs. Ask for a new tool or feature, tell us what is awkward in your workflow, or ask a question: every request is read. For a security problem, follow SECURITY.md instead of opening an issue.

📄 License

Apache License 2.0. The license does not cover the project name: forks are welcome under another name. This project is an independent implementation and is not affiliated with Docmost. It was inspired by docmost-mcp-oss.