Skip to content
Conduit

mcp server

mkdocs-mcp

Generic, configurable MCP server that makes any MkDocs documentation site searchable and explorable from MCP clients (Claude, IDEs) over streamable HTTP. BM25 + optional hybrid semantic search

ehsanmsb/mkdocs-mcpcommunitylistedunreviewed
Use tool

Set up

Runs on your computer. Pick your agent and operating system.

Before you start

  • uv (`curl -LsSf https://astral.sh/uv/install.sh | sh`)
~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "mkdocs-mcp": {
      "command": "uvx",
      "args": [
        "mkdocs-mcp"
      ]
    }
  }
}

same format Cursor, GitHub Copilot CLI, Junie, JetBrains AI Assistant, Augment (Auggie CLI), Factory Droid, Kiro, Devin CLI +12

Values in angle brackets are placeholders. Restart Claude Desktop after editing its config.Claude Desktop docs

README

synced Oct 23, 2026

MkDocs MCP Server

Build and Release Latest release License

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"
    }
  }
}

Documentation

↑↓ navigate openesc close