io.github.ubaumann/mkdocs-mcp

Official

by ubaumann · Python

An MCP server that provides serves MkDocs as resources.

MkDocs MCP Server (`io.github.ubaumann/mkdocs-mcp`)

An MCP server that serves MkDocs resources and integrates an MCP server into the MkDocs workflow. The project is described as an experimental proof-of-concept, with limitations in MkDocs preventing overriding the native mkdocs serve command.

🛠️ Key Features

Provides an experimental MkDocs plugin to integrate an MCP server into the MkDocs workflow
Cannot override MkDocs native mkdocs serve due to stated limitations
Includes a mkdocs_mcp script to handle the build process and launch the MCP server

🚀 Use Cases

Serving MkDocs content as MCP-accessible resources
Running an MCP server alongside the MkDocs build, without replacing mkdocs serve

⚡ Developer Benefits

Offers a script (mkdocs_mcp) that manages building and launching the MCP server
Uses uv for dependency management and virtual environments

⚠️ Limitations

MkDocs limitations prevent overriding the native mkdocs serve command

README.md2 KBView on GitHub

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:

bash

uv run mkdocs-mcp -mt stdio

Use the --mkdocs-project-path option to specify the path to your MkDocs project if it's not in the current directory. The environment variable MKDOCS_PROJECT_PATH can also be set for this purpose.

MkDocs Configuration

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

yaml

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

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):

json

{
  "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, you can directly inspect the MCP server:

bash

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

Install

Configuration

Environment variables

MKDOCS_PROJECT_PATHrequired

Path to the MkDocs project

Add to VS Code Add to Cursor

claude_desktop_config.json