papermoon-mkdocs-mcp

Ein leichtgewichtiger MCP-Server für MkDocs-Dokumentationsseiten. Liest Markdown-Dateien direkt von der Festplatte, bietet Volltext- und optionale semantische Suche und stellt die Projektstruktur über das Model Context Protocol bereit.

Funktionen

• 5 MCP-Tools – Suche, read_document, list_documents, get_project_info, get_document_outline

• SQLite-FTS5-Keyword-Suche mit BM25-Ranking (keine externen Abhängigkeiten)

• Optionale semantische Vektorsuche über sentence-transformers

• Hybride Suche kombiniert Keyword- und Vektor-Ergebnisse mit Reciprocal Rank Fusion

• Inkrementelle Indizierung – schnelle Updates bei Dateiänderungen

• Persistenter SQLite-Index, der Server-Neustarts übersteht

• Navigationsbewusst – parst mkdocs.yml und .nav.yml

• Ausschließbare Dokumente – Entwürfe und interne Seiten vom MCP-Surface fernhalten

• Sicherheit zuerst – Path-Traversal-Schutz, schreibgeschützte Suchverbindungen

• Minimale Abhängigkeiten – 3 erforderlich, 2 optional

Related MCP server: mdbook-mcp-server

Installation

pip install papermoon-mkdocs-mcp

Um die Vektorsuche zu aktivieren:

pip install papermoon-mkdocs-mcp[vector]

Schnellstart

Führen Sie den Befehl im Stammverzeichnis eines beliebigen MkDocs-Projekts aus (dort, wo mkdocs.yml liegt):

cd /path/to/your/mkdocs-project
papermoon-mkdocs-mcp

Oder zeigen Sie auf eine bestimmte Konfigurationsdatei:

papermoon-mkdocs-mcp --config /path/to/mkdocs.yml

Der Server erkennt mkdocs.yml im aktuellen Verzeichnis automatisch, wenn --config weggelassen wird.

Transportoptionen

Standardmäßig verwendet der Server den stdio-Transport. Sie können für Remote- oder Multi-Client-Setups auf einen Netzwerktransport umschalten:

# Streamable HTTP (recommended for network access)
papermoon-mkdocs-mcp --transport streamable-http --host 0.0.0.0 --port 9000

# SSE (legacy client compatibility)
papermoon-mkdocs-mcp --transport sse --port 8080

Sicherheitshinweis: Wenn Sie an eine Nicht-Loopback-Adresse binden, platzieren Sie den Server hinter einem Reverse-Proxy (z. B. nginx, Caddy), der TLS beendet.

MCP-Client-Konfiguration

Claude Desktop

Fügen Sie zu Ihrer Claude-Desktop-Konfigurationsdatei hinzu:

{
  "mcpServers": {
    "mkdocs": {
      "command": "papermoon-mkdocs-mcp",
      "args": ["--config", "/path/to/mkdocs.yml"]
    }
  }
}

Hinweis: Wenn Claude Desktop den Befehl nicht finden kann (Failed to spawn process: No such file or directory), verwenden Sie den vollständigen Pfad zur ausführbaren Datei anstelle von nur mkdocs-mcp:

{
  "mcpServers": {
    "mkdocs": {
      "command": "/path/to/.venv/bin/mkdocs-mcp",
      "args": ["--config", "/path/to/mkdocs.yml"]
    }
  }
}

Dies ist häufig der Fall, wenn das Paket in einer virtuellen Umgebung installiert ist, deren bin/-Verzeichnis nicht im PATH von Claude Desktop liegt.

Claude Code / VS Code

Fügen Sie .mcp.json im Stammverzeichnis Ihres Projekts hinzu:

{
  "mcpServers": {
    "mkdocs": {
      "command": "papermoon-mkdocs-mcp",
      "args": ["--config", "/path/to/mkdocs.yml"]
    }
  }
}

Verfügbare Tools

search

Durchsuchen Sie die Dokumentation mit Keyword-, semantischer oder hybrider Suche.

Gibt sortierte Ergebnisse mit Pfad, Titel, Relevanzwert (normalisiert 0,0–1,0) und Textausschnitt zurück.

read_document

Liest eine Dokumentationsdatei anhand ihres relativen Pfads.

Gibt den Markdown-Body (ohne Frontmatter), das geparste Frontmatter als separates Feld, die Überschriftenstruktur und Dateimetadaten zurück.

list_documents

Listet alle Dokumentationsdateien auf, optional nach Abschnitt gefiltert.

Gibt Dokumentmetadaten zurück (Pfad, Titel, Beschreibung, Kategorien, Größe, mtime).

get_project_info

Ruft Metadaten des MkDocs-Projekts ab. Nimmt keine Parameter entgegen.

Gibt Site-Name, Site-URL, Docs-Verzeichnis, Theme, Navigationsbaum, Dokumentanzahl und Indexstatus zurück.

get_document_outline

Ruft die Überschriftenstruktur (Inhaltsverzeichnis) für ein Dokument ab.

Gibt den Dokumenttitel und eine Liste von Überschriften mit Ebene, Text und Anker zurück.

Ausschließen von Dokumenten

Einige Markdown-Dateien sind es nicht wert, über MCP bereitgestellt zu werden – Entwürfe, interne Runbooks, generierte Notizdateien. Fügen Sie eine mcp_exclude-Liste zu mkdocs.yml hinzu:

site_name: My Docs

mcp_exclude:
  - drafts/             # any directory named 'drafts', at any depth
  - internal/**         # anchored: only 'internal/' at the docs root
  - "*-scratch.md"      # by filename suffix, at any depth
  - "!internal/public.md"  # re-include one file from a broader rule

Ausschlüsse gelten überall gleichzeitig. Ein ausgeschlossenes Dokument fehlt im Navigationsbaum, gelangt nie in den Suchindex, erscheint nicht in list_documents und wird von read_document und get_document_outline abgelehnt – die Ablehnung ist identisch mit der Antwort für eine nicht vorhandene Datei, sodass nicht preisgegeben wird, dass das Dokument existiert.

mcp_exclude betrifft nur diesen MCP-Server. Es ändert nicht, was mkdocs build veröffentlicht.

Mustersyntax

Muster sind im Gitignore-Stil und werden gegen den Pfad eines Dokuments relativ zu docs_dir abgeglichen.

• Ein Muster, das / enthält, ist an docs_dir verankert; eines ohne / passt in beliebiger Tiefe.

• Ein abschließendes / beschränkt ein Muster auf Verzeichnisse, sodass drafts/ eine Datei namens drafts.md nicht versteckt.

• Regeln werden in der Reihenfolge ausgewertet, und die letzte Übereinstimmung entscheidet. Setzen Sie !-Wiedereinschlüsse also nach der Regel, aus der sie ausgenommen werden.

• Leere Zeilen und #-Kommentare werden ignoriert.

Neu ausgeschlossene Dateien werden beim nächsten Lauf aus dem Index entfernt, und das Entfernen eines Musters bringt sie zurück – es ist nicht nötig, .mkdocs-mcp.db zu löschen.

Architektur

src/mkdocs_mcp/
  config.py      -- MkDocs config detection and nav parsing
  exclusions.py  -- mcp_exclude pattern matching
  repository.py  -- SQLite schema and CRUD operations
  indexer.py     -- Index orchestration with incremental updates
  searcher.py    -- Keyword, vector, and hybrid search
  server.py      -- FastMCP server with 5 tool definitions
  utils.py       -- Path validation, frontmatter parsing, text extraction
  models.py      -- Pydantic response models

Beim Start liest der Server mkdocs.yml, scannt das Docs-Verzeichnis und erstellt (oder aktualisiert inkrementell) einen SQLite-FTS5-Index. Suchanfragen treffen direkt auf den Index; die Vektorsuche bettet die Abfrage mit all-MiniLM-L6-v2 ein und vergleicht sie mit gespeicherten Dokument-Embeddings. Der Hybridmodus führt beide Ergebnislisten mithilfe von Reciprocal Rank Fusion zusammen.

Entwicklung

git clone https://github.com/aspect-build/mkdocs-mcp.git
cd mkdocs-mcp
pip install -e ".[dev]"
pytest

Linting und Typprüfung:

ruff check .
mypy src/

Anforderungen

• Python >= 3.10

• Erforderlich: fastmcp (>=3.0, <4), pydantic (>=2.0, <3), pyyaml (>=6.0), markdown (>=3.4)

• Optional (Vektorsuche): sentence-transformers (>=3.0), numpy (>=1.24)

Lizenz

Siehe LICENSE für Details.