@wisflux/docmost-local-mcp

MCP server for Docmost that is built for self-hosted instances, especially deployments that do not have an enterprise license but still want reliable MCP access from local IDEs and AI tools.

The package is launched with npx, while the actual server is a Rust binary downloaded from GitHub Releases during install. That binary handles stdio MCP traffic, local authentication UX, session storage, and Docmost API access.

The main reason this project exists: bring MCP access to self-hosted Docmost setups without making an enterprise license a prerequisite.

Why This Project

Many MCP integrations are designed around hosted or enterprise assumptions. This project is intentionally optimized for self-hosted Docmost:

• Works against your own Docmost base URL
• Uses Docmost email/password authentication
• Stores session state locally for reuse
• Opens a local auth flow instead of requiring a separate hosted control plane
• Ships as a simple npx entrypoint for easy IDE integration

If you run your own Docmost and want it available inside Cursor, Claude Desktop, or another MCP client, this package is the straightforward path.

Highlights

• Strong fit for self-hosted Docmost instances without enterprise licensing
• Rust server core with a small Node launcher for predictable local installs
• Native auth window on supported platforms, with browser fallback
• Explicit Docmost instance selection via startup config
• Session reuse with JWT expiry checks and automatic re-login
• OS keychain credential storage on supported platforms
• Clean tool surface for spaces, pages, comments, members, and current user context

Available Tools

• list_spaces: list available Docmost spaces
• get_space: fetch details for a specific space
• search_docs: search documentation, optionally scoped to a space
• search_pages: backward-compatible alias for search_docs
• get_page: fetch a page and return its content as Markdown
• list_pages: list recent pages in a space
• list_child_pages: list child pages for a parent page ID
• get_comments: list comments for a page
• list_workspace_members: list workspace members
• get_current_user: fetch the authenticated user and workspace context
• create_page: create a new page in a space from Markdown content
• update_page: update an existing page's title and/or Markdown content
• duplicate_page: duplicate a page (and its sub-pages) within its space
• copy_page_to_space: copy a page (and its sub-pages) into a different space
• move_page: move a page under a new parent page, or to the space root
• move_page_to_space: move a page (and its sub-pages) to a different space
• create_space: create a new space with a name and URL slug
• update_space: update a space's name, slug, and/or description
• create_comment: add a page-level comment to a page from Markdown
• update_comment: replace an existing comment's body with new Markdown

Roadmap

All planned read and write tools are now implemented. create_comment adds page-level comments; comments anchored to a specific text selection (inline comments) require the collaborative editor's cursor positions and are out of scope for this REST-based server.

Compatibility

Targets Docmost from roughly the last year of releases (v0.22+); older servers work best-effort. The server detects the Docmost version (via POST /api/version) once per session and adapts where behaviour differs:

• Page body edits: update_page can only change an existing page's body on Docmost v0.70.0+. On older servers the body lives in the collaborative editor and a REST body update is ignored — update_page says so explicitly and suggests create_page (which persists bodies on every version via the import endpoint). Title updates work everywhere.

Content support

Page and comment bodies are written in Markdown (headings, bold/italic/strike, inline code, links, lists, task lists, blockquotes, code blocks; pages also support tables and external-URL images). Comments support a smaller set — no tables, task lists, or images.

Mentions (@tagging): in any Markdown body, a link with a user: or page: URL becomes a mention — [Display Name](user:USER_UUID) tags a user (find the UUID with list_workspace_members) and [Page Title](page:PAGE_UUID) links a page. Tagged users are notified by Docmost.

Attaching uploaded files/images (as opposed to referencing an image URL) is not supported.

Requirements

• Node.js 18 or newer for npx
• A reachable Docmost instance
• Email/password authentication enabled in that Docmost instance

Quick Start

Run the server directly with npx:

npx -y @wisflux/docmost-local-mcp --base-url=https://docs.example.com

You can also provide the base URL with an environment variable:

DOCMOST_BASE_URL=https://docs.example.com npx -y @wisflux/docmost-local-mcp

MCP Client Configuration

Most MCP clients launch the server directly with npx. Add this to your client's MCP config, replacing the base URL with your own Docmost instance:

{
  "mcpServers": {
    "docmost": {
      "command": "npx",
      "args": ["-y", "@wisflux/docmost-local-mcp", "--base-url=https://docs.example.com"]
    }
  }
}

Where that config lives, per client:

• Claude Desktop — claude_desktop_config.json (Settings → Developer → Edit Config)

• Cursor — ~/.cursor/mcp.json (global) or .cursor/mcp.json (per project)

• Claude Code — one command, no file editing:

  hljs language-bash

  Copy

  claude mcp add docmost -- npx -y @wisflux/docmost-local-mcp --base-url=https://docs.example.com
  

• VS Code (GitHub Copilot) — .vscode/mcp.json, using a top-level servers key instead of mcpServers:

  hljs language-json

  Copy

  {
    "servers": {
      "docmost": {
        "command": "npx",
        "args": ["-y", "@wisflux/docmost-local-mcp", "--base-url=https://docs.example.com"]
      }
    }
  }
  

This setup works well when you want a fixed Docmost instance per client configuration. If --base-url or DOCMOST_BASE_URL is set, the login page shows that URL prefilled and locks the field. If no base URL is configured, the login flow asks for it during interactive sign-in.

Example Prompts

Once connected, ask your AI client things like:

• "Search the Engineering space in Docmost for our on-call runbook and summarize it."
• "Create a new page in the Product space titled 'Q3 Planning' from these notes: …"
• "Turn this meeting transcript into a structured Docmost page under the Team space."
• "Find every page in Docmost that mentions the old API endpoint and list them."
• "Read the 'Onboarding' page and draft a shorter checklist as a new sub-page."
• "Add a comment on the release-notes page flagging the missing migration step."

Authentication Flow

1. Your MCP client launches the server over stdio.
2. On the first authenticated tool call, the server starts a local HTTP login page on 127.0.0.1.
3. The server opens a native auth window when available, or falls back to the system browser.
4. You enter your email and password there. If --base-url or DOCMOST_BASE_URL is set, the Docmost URL is prefilled and locked.
5. The server signs in through /api/auth/login, extracts the authToken cookie, stores the session, and optionally stores credentials for automatic re-login.
6. Future requests reuse the saved token until it is close to expiry or rejected by Docmost.

Local State And Credential Storage

The server stores local state in:

~/.docmost-local-mcp/

Files used there:

• config.json: last base URL and email
• session.json: saved auth token and expiry

Credentials are stored in the OS keychain when available, which is the preferred path on supported platforms.

If secure OS credential storage is unavailable, the server falls back to encrypted local credential storage so it can still support login reuse without writing plain-text credentials. That fallback is intentionally secondary to keychain-backed storage.

Platform Notes

The native auth window uses the system webview on each platform:

• macOS: WKWebView
• Windows: WebView2
• Linux: WebKitGTK

Important caveats:

• Windows needs the WebView2 runtime available
• Linux desktop environments need WebKitGTK packages installed
• When the binary is built without the native-webview feature, browser fallback is always used

Tool Reference

list_spaces

Returns Docmost space names, slugs, and IDs.

search_docs

Inputs:

• query: required search text
• space_id: optional Docmost space ID

search_pages

Inputs:

• query: required search text
• space_id: optional Docmost space ID

This is a backward-compatible alias for page search. search_docs remains available.

get_space

Inputs:

• space_id: required Docmost space ID

get_page

Inputs:

• slug_id: the page slug ID returned by search_docs

list_pages

Inputs:

• space_id: required Docmost space ID
• limit: optional page count limit
• cursor: optional pagination cursor

list_child_pages

Inputs:

• page_id: required parent page ID
• limit: optional page count limit
• cursor: optional pagination cursor

get_comments

Inputs:

• page_id: required page ID
• limit: optional comment count limit
• cursor: optional pagination cursor

list_workspace_members

Inputs:

• limit: optional member count limit
• cursor: optional pagination cursor
• query: optional member search text
• admin_view: optional admin visibility flag

get_current_user

Inputs:

• none

create_page

Inputs:

• space_id: required Docmost space ID (UUID) to create the page in
• title: required page title
• markdown: optional page body as Markdown
• parent_page_id: optional parent page ID to nest under (title-only pages only)

When markdown is provided, the page body is sent through Docmost's import endpoint (POST /api/pages/import), which is the only mechanism that reliably persists page body content across Docmost versions (including older self-hosted servers). Pages created with a body land at the space root — parent_page_id is honored only for title-only pages.

update_page

Inputs:

• page_id: required Docmost page ID or slug ID
• title: optional new title (omit to leave unchanged)
• markdown: optional new body as Markdown; replaces the existing content (omit to leave unchanged)

Updating a page title works on all Docmost versions. Updating an existing page's body via REST works only on newer Docmost; on older self-hosted servers (e.g. v0.25.x) the body is edited solely through the collaborative editor and a REST body update is not applied. To set body content reliably there, create a new page with create_page instead.

For the full design, Markdown→ProseMirror conversion details, verified Docmost API fields, and version caveats, see docs/write-tools.md.

Development

For maintainer and contributor workflow details, see CONTRIBUTING.md.

License

MIT