mkdocs-mcp

MkDocs Plugin to Serve MCP
A proof-of-concept — feedback welcome!

mkdocs-mcp is an experimental plugin designed to integrate an MCP server into the MkDocs workflow. Due to limitations in MkDocs, the native mkdocs serve command cannot be overridden. Instead, this project provides the mkdocs_mcp script to handle the build process and launch the MCP server.

Quick Start

Requirements

This project uses uv for dependency management and virtual environments.

Running the MCP Server

To start the MCP server:

uv run python src/mkdocs_mcp/ -mt stdio

MkDocs Configuration

Make sure to include mcp in your mkdocs.yml plugin list:

plugins:
  - mcp:
      naming_style: src_file  # "src_file"(default), "dst_url" or "title"
      prefer_markdown: True  # By default the source markdown is used, set to False to convert the output HTML to markdown

Using Claude Desktop with WSL

If you're working with Claude Desktop and WSL, configure your claude_desktop_config.json as follows (adjust paths as needed):

{
  "mcpServers": {
    "mkdocs": {
      "command": "wsl.exe",
      "args": [
        "bash",
        "-c",
        "/home/urs/.cargo/bin/uv run --directory /home/urs/projects/mkdocs-mcp python src/mkdocs_mcp/ -mt stdio"
      ]
    }
  }
}

Inspecting the MCP Server

For development and debugging, you can directly inspect the MCP server:

uv run mcp dev src/mkdocs_mcp/__main__.py

Notes

• This project is still in the early proof-of-concept stage.
• Contributions and feedback are highly encouraged!

Thanks for checking out mkdocs-mcp!