# 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`](https://github.com/astral-sh/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](https://github.com/mcp) mcp-name: io.github.ubaumann/mkdocs-mcp