MkDocs MCP Server

A read-only Model Context Protocol server for public MkDocs sites that publish a search index. It searches the published search/search_index.json and returns relevant sections, page text, and links over HTTP. It does not clone the documentation repository or require MCP client authentication.

Quick start

Requires Python 3.14 and uv.

uv sync --locked --python 3.14
source .venv/bin/activate
export MKDOCS_MCP_SITES='[{"name":"docs","base_url":"https://docs.example.com"}]'
mkdocs-mcp

Replace the example URL with the public root of your MkDocs site. The server fetches <base_url>/search/search_index.json on startup and serves MCP at http://localhost:8000/mcp. If the index is elsewhere, add search_index_url to that site's object. The index must be reachable when the server starts.

Opening / in a browser shows the server status and MCP connection URL. Opening /mcp in a browser shows the same page; MCP clients continue to use /mcp for protocol requests.

To search several sites through the same endpoint, add more entries to MKDOCS_MCP_SITES. Search results identify their site and link to the original pages:

export MKDOCS_MCP_SITES='[{"name":"atlas","base_url":"https://atlas.example.com"},{"name":"team","base_url":"https://team.example.com"}]'

The server searches all configured sites with one BM25 index. A site that fails to refresh keeps its last good content; other sites remain searchable.

For MCP clients that use an mcpServers JSON configuration:

{
  "mcpServers": {
    "mkdocs-docs": {
      "type": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

Related MCP server: mcp-docs

Documentation

• Configuration and environment variables

• Logs, metrics, dashboards, and alerts

• Tools, search behavior, and limitations

• Deployment on Kubernetes and OpenShift

• Releases and versioning

• Contributing and tests