papermoon-mkdocs-mcp

A lightweight MCP server for MkDocs documentation sites. Reads markdown files directly from disk, provides full-text and optional semantic search, and exposes project structure through the Model Context Protocol.

Features

• 5 MCP tools -- search, read_document, list_documents, get_project_info, get_document_outline
• SQLite FTS5 keyword search with BM25 ranking (zero external dependencies)
• Optional semantic vector search via sentence-transformers
• Hybrid search combining keyword + vector results with Reciprocal Rank Fusion
• Incremental indexing -- fast updates when files change
• Persistent SQLite index that survives server restarts
• Navigation-aware -- parses mkdocs.yml and .nav.yml
• Excludable documents -- keep drafts and internal pages off the MCP surface
• Security-first -- path traversal prevention, read-only search connections
• Minimal dependencies -- 3 required, 2 optional

Installation

pip install papermoon-mkdocs-mcp

To enable vector search:

pip install papermoon-mkdocs-mcp[vector]

Quick Start

Run from the root of any MkDocs project (where mkdocs.yml lives):

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

Or point to a specific config file:

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

The server auto-detects mkdocs.yml in the current directory when --config is omitted.

Transport Options

By default the server uses stdio transport. You can switch to a network transport for remote or multi-client setups:

# 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

Flag	Default	Description
--transport	stdio	stdio, sse, or streamable-http
--host	127.0.0.1	Bind address (network transports only)
--port	8000	Bind port (network transports only)

Security note: When binding to a non-loopback address, place the server behind a reverse proxy (e.g. nginx, Caddy) that terminates TLS.

MCP Client Configuration

Claude Desktop

Add to your Claude Desktop configuration file:

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

Note: If Claude Desktop can't find the command (Failed to spawn process: No such file or directory), use the full path to the executable instead of just mkdocs-mcp:

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

This is common when the package is installed in a virtual environment whose bin/ directory isn't in Claude Desktop's PATH.

Claude Code / VS Code

Add to .mcp.json in your project root:

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

Available Tools

search

Search documentation using keyword, semantic, or hybrid search.

Parameter	Type	Default	Description
query	str	(required)	The search query string
search_type	str	"hybrid"	"keyword", "vector", or "hybrid"
max_results	int	10	Maximum results to return (1--100)

Returns ranked results with path, title, relevance score (normalized 0.0--1.0), and text snippet.

read_document

Read a documentation file by its relative path.

Parameter	Type	Default	Description
path	str	(required)	Relative path from docs dir (e.g. guide/setup.md)

Returns the markdown body (frontmatter stripped), parsed frontmatter as a separate field, heading structure, and file metadata.

list_documents

List all documentation files, optionally filtered by section.

Parameter	Type	Default	Description
section	str or null	null	Directory prefix to filter by (e.g. guide)

Returns document metadata (path, title, description, categories, size, mtime).

get_project_info

Get MkDocs project metadata. Takes no parameters.

Returns site name, site URL, docs directory, theme, navigation tree, document count, and index status.

get_document_outline

Get the heading structure (table of contents) for a document.

Parameter	Type	Default	Description
path	str	(required)	Relative path from docs dir (e.g. guide/setup.md)

Returns the document title and a list of headings with level, text, and anchor.

Excluding Documents

Some markdown files are not worth exposing over MCP -- drafts, internal runbooks, generated scratch files. Add an mcp_exclude list to mkdocs.yml:

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

Exclusions apply everywhere at once. An excluded document is absent from the navigation tree, never enters the search index, does not appear in list_documents, and is refused by read_document and get_document_outline -- the refusal is identical to the response for a file that does not exist, so it does not reveal that the document is there.

mcp_exclude affects only this MCP server. It does not change what mkdocs build publishes.

Pattern syntax

Patterns are gitignore-style and match against a document's path relative to docs_dir.

Pattern	Matches
drafts/	Any directory named drafts and everything under it
/drafts/	Only drafts/ at the docs root
internal/**	Everything under a root-level internal/
*.tmp.md	Files ending .tmp.md, at any depth
guide/*.md	.md files directly in guide/ (not in subdirectories)
guide/**/*.md	.md files anywhere under guide/
draft?.md	draft1.md, draftx.md -- ? is a single character
draft[0-9].md	A character class
!keep/this.md	Re-includes a path an earlier pattern excluded

• A pattern containing / is anchored at docs_dir; one without it matches at any depth.
• A trailing / restricts a pattern to directories, so drafts/ does not hide a file named drafts.md.
• Rules are evaluated in order and the last one to match decides, so put ! re-inclusions after the rule they carve out of.
• Blank lines and # comments are ignored.

Newly excluded files are dropped from the index on the next run, and removing a pattern brings them back -- no need to delete .mkdocs-mcp.db.

Architecture

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

At startup the server reads mkdocs.yml, scans the docs directory, and builds (or incrementally updates) a SQLite FTS5 index. Search queries hit the index directly; vector search embeds the query with all-MiniLM-L6-v2 and compares against stored document embeddings. Hybrid mode fuses both result lists using Reciprocal Rank Fusion.

Development

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

Linting and type checking:

ruff check .
mypy src/

Requirements

• Python >= 3.10
• Required: fastmcp (>=3.0, <4), pydantic (>=2.0, <3), pyyaml (>=6.0), markdown (>=3.4)
• Optional (vector search): sentence-transformers (>=3.0), numpy (>=1.24)

License

See LICENSE for details.