mkdocs-mcp — Claude Code MCP server: what it does, how to install
Exposes MkDocs documentation sites as MCP resources for AI tools. Helpful when an assistant needs direct access to local project docs.
claude mcp add mkdocs-mcp -e MKDOCS_PROJECT_PATH=<MKDOCS_PROJECT_PATH> -- uvx mkdocs-mcpWhat mkdocs-mcp does
This server turns an MkDocs site into Model Context Protocol resources. MkDocs architecture prevents overriding the built-in mkdocs serve command directly. To handle this, the package runs via its own mkdocs-mcp CLI script, which builds the docs and starts an MCP stdio server.
Running the tool requires the uv package manager. You point it to your repository by passing --mkdocs-project-path or setting the MKDOCS_PROJECT_PATH environment variable.
Your mkdocs.yml file must list mcp inside the plugins section. The configuration lets you select resource naming (src_file, dst_url, or title), serve original Markdown instead of converted HTML, or aggregate documents by folder. Leaving the plugin entry out of mkdocs.yml breaks the connection.
What it helps with
- Expose MkDocs project pages as MCP resources to an AI assistant
- Serve raw Markdown source directly instead of converting generated HTML
- Combine documentation pages by directory or merge them into one resource
- Connect local documentation on WSL to Claude Desktop
Example prompts for the agent
- Read the installation guide from the connected MkDocs resources and check the prerequisites.
- Search the local MkDocs documentation resources for plugin configuration examples.
How to install mkdocs-mcp
Platform CLI
claude mcp add mkdocs-mcp -e MKDOCS_PROJECT_PATH=<MKDOCS_PROJECT_PATH> -- uvx mkdocs-mcpReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from mkdocs-mcp <command>
Platform CLI
codex mcp add mkdocs-mcp --env MKDOCS_PROJECT_PATH=<MKDOCS_PROJECT_PATH> -- uvx mkdocs-mcpReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from mkdocs-mcp <command>
Config file
{
"mcpServers": {
"mkdocs-mcp": {
"command": "uvx",
"args": [
"mkdocs-mcp"
],
"env": {
"MKDOCS_PROJECT_PATH": "<MKDOCS_PROJECT_PATH>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from mkdocs-mcp <command>
Config file
{
"servers": {
"mkdocs-mcp": {
"type": "stdio",
"command": "uvx",
"args": [
"mkdocs-mcp"
],
"env": {
"MKDOCS_PROJECT_PATH": "<MKDOCS_PROJECT_PATH>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from mkdocs-mcp <command>
Platform CLI
gemini mcp add -e MKDOCS_PROJECT_PATH=<MKDOCS_PROJECT_PATH> mkdocs-mcp uvx mkdocs-mcpReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from mkdocs-mcp <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about mkdocs-mcp
How to install mkdocs-mcp in Claude Code?
Run claude mcp add mkdocs-mcp -e MKDOCS_PROJECT_PATH=<MKDOCS_PROJECT_PATH> -- uvx mkdocs-mcp, replacing <MKDOCS_PROJECT_PATH> with your MkDocs project directory.
What does mkdocs-mcp do?
It runs an MCP server that provides pages from an MkDocs site as readable resources over stdio.
Why does it require a custom script instead of mkdocs serve?
MkDocs does not allow overriding its native mkdocs serve command, so mkdocs-mcp handles the site build and server startup on its own.
