docmost-mcp

An MCP server that gives AI agents read/write access to a self-hosted Docmost wiki through its regular REST API.

Why this exists

Docmost ships its own MCP endpoint, but it is gated behind a paid licence — the Settings UI shows "Available with a paid license" for API management, and /api/mcp returns 404 on the Community Edition. Minting API keys is gated the same way.

The ordinary REST API, however, is fully open in the Community Edition. This server is a thin wrapper over it: same operations, session authentication instead of an API key.

Requirements

• Python 3.11+
• A Docmost instance you can reach over HTTP(S)
• A dedicated Docmost user account for the agent

Install

git clone https://github.com/<you>/docmost-mcp.git
cd docmost-mcp
python3 -m venv venv
./venv/bin/pip install -r requirements.txt

Configure

Copy the example config and fill it in:

cp config.example.json config.json
chmod 600 config.json

{
  "url": "https://docmost.example.com",
  "api_key": "",
  "email": "agent@example.com",
  "password": "..."
}

Two authentication modes are supported:

Mode	When to use
api_key	If you hold a Docmost Enterprise licence. Sent as a Bearer token.
email + password	Community Edition. The server logs in and re-authenticates automatically when the session expires.

If api_key is set it takes precedence; otherwise the credentials are used.

The config path can be overridden with the DOCMOST_MCP_CONFIG environment variable.

Create a dedicated account

Do not use the workspace owner's credentials. Invite a separate user (Settings → Members → Invite) and grant it access only to the spaces the agent needs. Space access in Docmost is usually inherited from the default Everyone group, so check what that group can reach before assuming the agent is restricted.

Gmail-style plus-addressing (you+agent@gmail.com) works if you would rather not create a second mailbox.

Verify

selftest.py exercises the whole chain — login, read, write, read back, delete:

./venv/bin/python selftest.py

Connecting an agent

The server speaks MCP over stdio.

Claude Code

claude mcp add docmost -- /path/to/docmost-mcp/venv/bin/python /path/to/docmost-mcp/server.py

Or add it to ~/.claude.json by hand:

{
  "mcpServers": {
    "docmost": {
      "type": "stdio",
      "command": "/path/to/docmost-mcp/venv/bin/python",
      "args": ["/path/to/docmost-mcp/server.py"],
      "env": {}
    }
  }
}

Restart Claude Code afterwards — the configuration is read at startup.

Claude Desktop

Add the same block to claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Cursor

Add it to .cursor/mcp.json in the project, or to ~/.cursor/mcp.json globally, using the same mcpServers shape.

Any other MCP client

Launch server.py with the virtualenv's Python and speak JSON-RPC over stdin and stdout. A minimal handshake:

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"probe","version":"1"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/list"}

A convenience wrapper keeps the command short:

#!/bin/sh
exec /path/to/docmost-mcp/venv/bin/python /path/to/docmost-mcp/server.py "$@"

Tools

Tool	Arguments	Does
list_spaces	limit	Lists workspace spaces
search	query, space_id?, limit	Full-text search across pages
get_page	page_id	Fetches a page by id or slugId
recent_pages	space_id?, limit	Recently changed pages
create_page	space_id, title, content?, parent_page_id?, fmt	Creates a page
update_page	page_id, title?, content?, fmt	Updates title and/or body
move_page	page_id, parent_page_id?	Reparents a page
delete_page	page_id, permanently	Trashes (or permanently deletes) a page

fmt is markdown (default), html or json.

Notes on the Docmost API

Things worth knowing if you extend this server:

• Every endpoint is POST, including reads.
• /pages/create and /pages/update require a format field (json | markdown | html). Omitting it returns 400.
• Responses wrap the payload in {"data": ...}; the client unwraps it.
• /api/api-keys answers 200 with an empty list on the Community Edition — listing is open, only key creation is licence-gated.
• Endpoint paths and payload shapes were taken from the Docmost client source (apps/client/src/features/*/services/*.ts), not guessed.

Security

• config.json holds a plaintext password. Keep it at mode 600 and out of version control — it is in .gitignore.
• Give the agent account the narrowest space access that still lets it work.
• The account's actions appear in Docmost under its own name, so page history stays attributable.

Compatibility

Built against Docmost 0.95.0 and Python MCP SDK 2.0. Note that SDK 2.0 renamed FastMCP to MCPServer and moved it to mcp.server; the pre-2.0 import path mcp.server.fastmcp will not work.

Licence

MIT — see LICENSE.

This project is not affiliated with Docmost.