MkDocs MCP Server
by ehsanmsb
README.md

# MkDocs MCP Server
[](https://github.com/ehsanmsb/mkdocs-mcp/actions/workflows/release.yml)
[](https://github.com/ehsanmsb/mkdocs-mcp/releases)
[](LICENSE)
A read-only [Model Context Protocol](https://modelcontextprotocol.io) server for
public [MkDocs](https://www.mkdocs.org/) sites that publish a search index. It
searches the published `search/search_index.json` and returns relevant
sections, page text, and links over HTTP. It does not clone the documentation
repository or require MCP client authentication.
## Quick start
Requires Python 3.14 and `uv`.
```bash
uv sync --locked --python 3.14
source .venv/bin/activate
export MKDOCS_MCP_SITES='[{"name":"docs","base_url":"https://docs.example.com"}]'
mkdocs-mcp
```
Replace the example URL with the public root of your MkDocs site. The server
fetches `<base_url>/search/search_index.json` on startup and serves MCP at
`http://localhost:8000/mcp`. If the index is elsewhere, add `search_index_url`
to that site's object. The index must be reachable when the server starts.
Opening `/` in a browser shows the server status and MCP connection URL.
Opening `/mcp` in a browser shows the same page; MCP clients continue to use
`/mcp` for protocol requests.
To search several sites through the same endpoint, add more entries to
`MKDOCS_MCP_SITES`. Search results identify their site and link to the original
pages:
```bash
export MKDOCS_MCP_SITES='[{"name":"atlas","base_url":"https://atlas.example.com"},{"name":"team","base_url":"https://team.example.com"}]'
```
The server searches all configured sites with one BM25 index. A site that
fails to refresh keeps its last good content; other sites remain searchable.
For MCP clients that use an `mcpServers` JSON configuration:
```json
{
"mcpServers": {
"mkdocs-docs": {
"type": "http",
"url": "http://localhost:8000/mcp"
}
}
}
```
## Documentation
- [Configuration and environment variables](docs/CONFIGURATION.md)
- [Logs, metrics, dashboards, and alerts](docs/OBSERVABILITY.md)
- [Tools, search behavior, and limitations](docs/USAGE.md)
- [Deployment on Kubernetes and OpenShift](charts/mkdocs-mcp/README.md)
- [Releases and versioning](docs/RELEASES.md)
- [Contributing and tests](docs/CONTRIBUTING.md)
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues