# mkdocs-mcp

Exposes MkDocs documentation sites as MCP resources for AI tools. Helpful when an assistant needs direct access to local project docs.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 9
- Author: ubaumann
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/ubaumann/mkdocs-mcp
- Updated: 2025-09-20
- HTML: https://affpapa.org/en/nevibecode/mcp/mkdocs-mcp

## What it 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.

## Requirements
- Needs: Python and uv (commands run via uvx)
- Environment variables: `MKDOCS_PROJECT_PATH` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add mkdocs-mcp -e MKDOCS_PROJECT_PATH=<MKDOCS_PROJECT_PATH> -- uvx mkdocs-mcp
```
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>

### Codex

**Platform CLI**
```bash
codex mcp add mkdocs-mcp --env MKDOCS_PROJECT_PATH=<MKDOCS_PROJECT_PATH> -- uvx mkdocs-mcp
```
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>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "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>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "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>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e MKDOCS_PROJECT_PATH=<MKDOCS_PROJECT_PATH> mkdocs-mcp uvx mkdocs-mcp
```
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>

## When to use it
- 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
- Read the installation guide from the connected MkDocs resources and check the prerequisites.
- Search the local MkDocs documentation resources for plugin configuration examples.

## Similar
- [kubernetes-mkdocs-documentation-cursorrules-prompt](https://affpapa.org/en/nevibecode/rules/kubernetes-mkdocs-documentation-cursorrules-prompt.md) — rule · ★ 41024
- [mkdocs-translations](https://affpapa.org/en/nevibecode/skills/mkdocs-translations.md) — skill · 8800 installs
- [developer-docs-structure-audit](https://affpapa.org/en/nevibecode/skills/developer-docs-structure-audit.md) — skill · 10200 installs
- [firecrawl-knowledge-ingest](https://affpapa.org/en/nevibecode/skills/firecrawl-knowledge-ingest.md) — skill · 31400 installs
- [Cantara wiki — community knowledge web](https://affpapa.org/en/nevibecode/mcp/cantara-wiki-community-knowledge-web.md) — MCP server
- [tavily-crawl](https://affpapa.org/en/nevibecode/skills/tavily-crawl.md) — skill · 17400 installs

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md