MkDocs MCP Server

A generic, configurable Model Context Protocol server that makes any MkDocs documentation site searchable and explorable from MCP clients (Claude CLI, IDEs, …).

Nothing is organization- or project-specific: the docs repo, URLs, tenants, topic taxonomy, and server identity are all supplied via configuration.

• Transport: streamable-http

• Search: BM25 (rank-bm25) with an optional self-hosted semantic/hybrid layer (sentence-transformers, fused with Reciprocal Rank Fusion)

• Source of truth: the docs git repo (with a search_index.json and a local fallback)

• Built on established libraries — FastMCP (auth, middleware, transport), markdown-it-py + python-markdown + python-frontmatter (parsing), pydantic-settings, structlog, prometheus-client.

Quick start (local)

uv pip install -e .

export MKDOCS_MCP_SOURCE_MODE=local
export MKDOCS_MCP_REPO_DIR=/path/to/your/mkdocs-repo
export MKDOCS_MCP_MKDOCS_CONFIG=mkdocs.yml
export MKDOCS_MCP_BASE_URL=https://docs.example.com
export MKDOCS_MCP_AUTH_MODE=none

mkdocs-mcp        # serves http://0.0.0.0:8000/mcp

Health: GET /health, readiness: GET /ready, metrics: :9000/metrics.

Related MCP server: mcp-docs

Connect from Claude CLI (HTTP)

{
  "mcpServers": {
    "mkdocs-docs": {
      "type": "http",
      "url": "https://mkdocs-mcp.example.com/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

Configuration

All settings are env vars prefixed MKDOCS_MCP_ (see src/mkdocs_mcp/config.py).

Custom topic taxonomy

# topics.yml  (MKDOCS_MCP_TOPICS_FILE=/path/topics.yml)
topics:
  payments:
    paths: ["/payments/"]
    keywords: ["checkout", "billing", "invoice"]

Tools

Search: search_docs, search_section, semantic_search Navigation: get_page, get_section, list_categories, list_pages, browse_tree Knowledge: summarize_page, related_documents, suggest_reading Discovery: recent_changes, find_runbooks, find_examples Topics: find_by_topic (+ find_<topic>_docs aliases generated from FEATURED_TOPICS) Admin: rebuild_index (admin scope), health_check, get_statistics

Auth

Static bearer tokens are verified by FastMCP's StaticTokenVerifier; admin tokens carry the admin scope, required by rebuild_index. To use JWT or an OAuth provider (Keycloak, GitHub, Google, …), change build_verifier in src/mkdocs_mcp/auth.py to the matching FastMCP provider — the tools are unaffected.

Semantic / hybrid search (optional)

uv pip install -e '.[vectors]'
export MKDOCS_MCP_EMBEDDINGS_ENABLED=true
export MKDOCS_MCP_EMBEDDINGS_MODEL=BAAI/bge-m3   # multilingual, self-hosted

Embeddings run in-process; no external embedding API is used.

Tests

uv pip install -e '.[dev]'
pytest
ruff check src tests

Contributing

See docs/CONTRIBUTING.md for development setup, validation, pull request expectations, and commit message rules.

Releases

This repository uses Semantic Versioning with semantic-release and Conventional Commits.

When a branch is merged into main, the release workflow analyzes the commits since the previous release, calculates the next version, creates the Git tag automatically, builds Python and Helm package artifacts, publishes a GitHub release with generated release notes, and pushes a GHCR image. The tag starts with v (for example, v1.2.3).

The release image is published to ghcr.io/<owner>/<repo> with these tags:

• <version> such as 1.2.3

• <major>.<minor> such as 1.2

• sha-<commit-sha>

• latest

Release notes are grouped into:

• Features

• Bug Fixes

• Performance

• Refactoring

Low-signal commit types such as docs:, test:, chore:, ci:, and build: are hidden from published release notes unless they include a breaking change.

Use standard Conventional Commit syntax:

• feat: add source adapter -> minor release

• fix: handle empty search index -> patch release

• perf: reduce indexing allocations -> patch release

• refactor: split parser metadata handling -> no version bump, but shown in release notes

• feat!: change configuration names -> major release

• BREAKING CHANGE: configuration names changed in the commit footer -> major release

Deployment

Container + Helm chart for OKD/OpenShift live in charts/mkdocs-mcp/. See charts/mkdocs-mcp/README.md.