Mkdocs MCP

🚀 mkdocs-mcp

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

This project is an experimental MkDocs plugin that integrates an MCP server into the MkDocs workflow. Due to the limitations of MkDocs, the native mkdocs serve command cannot be overridden. Instead, the mkdocs_mcp script is provided 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, use the following command:

uv run mkdocs-mcp -mt stdio

If your MkDocs project is not in the current directory, you can use the --mkdocs-project-path option to specify its path. You can also set the environment variable MKDOCS_PROJECT_PATH for this purpose.

⚙️ MkDocs Configuration

Ensure that you include mcp in the plugin list of your mkdocs.yml file:

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
      combine_all_pages: False  # Aggregate all pages into one file
      combine_by_folder: False  # Aggregate each folder

💻 Usage Examples

🖥️ Using Claude Desktop with WSL

If you are using Claude Desktop with WSL, configure your claude_desktop_config.json as follows (adjust the paths as necessary):

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

🔍 Inspecting the MCP Server

For development and debugging purposes, you can directly inspect the MCP server using the following command:

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!

GitHub MCP Registry mcp-name: io.github.ubaumann/mkdocs-mcp