papermoon-mkdocs-mcp

一个用于 MkDocs 文档站点的轻量级 MCP 服务器。直接从磁盘读取 markdown 文件，提供全文搜索和可选的语义搜索，并通过 Model Context Protocol 暴露项目结构。

功能

• 5 个 MCP 工具 -- search、read_document、list_documents、get_project_info、get_document_outline

• 基于 SQLite FTS5 的关键词搜索，使用 BM25 排序（零外部依赖）

• 通过 sentence-transformers 实现可选的语义向量搜索

• 混合搜索，结合关键词和向量结果，使用 Reciprocal Rank Fusion

• 增量索引 -- 文件变化时快速更新

• 持久化 SQLite 索引，服务器重启后依然存在

• 导航感知 -- 解析 mkdocs.yml 和 .nav.yml

• 可排除文档 -- 将草稿和内部页面排除在 MCP 表面之外

• 安全优先 -- 防止路径遍历，只读搜索连接

• 最小依赖 -- 3 个必需，2 个可选

Related MCP server: mdbook-mcp-server

安装

pip install papermoon-mkdocs-mcp

要启用向量搜索：

pip install papermoon-mkdocs-mcp[vector]

快速开始

在任何 MkDocs 项目的根目录下运行（即 mkdocs.yml 所在目录）：

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

或者指定特定的配置文件：

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

当省略 --config 时，服务器会自动检测当前目录中的 mkdocs.yml。

传输选项

默认情况下，服务器使用 stdio 传输。您可以切换到网络传输以用于远程或多客户端设置：

# 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

安全说明： 当绑定到非回环地址时，请将服务器放在终止 TLS 的反向代理（例如 nginx、Caddy）后面。

MCP 客户端配置

Claude Desktop

添加到您的 Claude Desktop 配置文件中：

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

注意： 如果 Claude Desktop 找不到该命令（Failed to spawn process: No such file or directory），请使用可执行文件的完整路径，而不是仅使用 mkdocs-mcp：

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

当包安装在虚拟环境中，且其 bin/ 目录不在 Claude Desktop 的 PATH 中时，这种情况很常见。

Claude Code / VS Code

添加到项目根目录的 .mcp.json 中：

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

可用工具

search

使用关键词、语义或混合搜索来搜索文档。

返回排序后的结果，包含路径、标题、相关性分数（归一化 0.0--1.0）和文本片段。

read_document

通过相对路径读取文档文件。

返回 markdown 正文（去除 frontmatter）、解析后的 frontmatter 作为单独字段、标题结构和文件元数据。

list_documents

列出所有文档文件，可选地按部分过滤。

返回文档元数据（路径、标题、描述、类别、大小、修改时间）。

get_project_info

获取 MkDocs 项目元数据。不接受参数。

返回站点名称、站点 URL、文档目录、主题、导航树、文档数量和索引状态。

get_document_outline

获取文档的标题结构（目录）。

返回文档标题和标题列表，包含级别、文本和锚点。

排除文档

有些 markdown 文件不值得通过 MCP 暴露——草稿、内部运行手册、生成的临时文件。在 mkdocs.yml 中添加 mcp_exclude 列表：

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

排除规则同时适用于所有地方。被排除的文档不会出现在导航树中，永远不会进入搜索索引，不会出现在 list_documents 中，并且会被 read_document 和 get_document_outline 拒绝——拒绝响应与文件不存在的响应相同，因此不会暴露该文档的存在。

mcp_exclude 仅影响此 MCP 服务器。它不会改变 mkdocs build 发布的内容。

模式语法

模式采用 gitignore 风格，匹配相对于 docs_dir 的文档路径。

• 包含 / 的模式锚定在 docs_dir；不包含 / 的模式匹配任意深度。

• 尾部 / 将模式限制为目录，因此 drafts/ 不会隐藏名为 drafts.md 的文件。

• 规则按顺序评估，最后匹配的规则决定结果，因此请将 ! 重新包含放在它们所排除的规则之后。

• 空行和 # 注释将被忽略。

新排除的文件将在下次运行时从索引中删除，移除模式后它们会重新出现——无需删除 .mkdocs-mcp.db。

架构

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

启动时，服务器读取 mkdocs.yml，扫描文档目录，并构建（或增量更新）SQLite FTS5 索引。搜索查询直接命中索引；向量搜索使用 all-MiniLM-L6-v2 对查询进行嵌入，并与存储的文档嵌入进行比较。混合模式使用 Reciprocal Rank Fusion 融合两个结果列表。

开发

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

代码检查和类型检查：

ruff check .
mypy src/

要求

• Python >= 3.10

• 必需： fastmcp (>=3.0, <4)、pydantic (>=2.0, <3)、pyyaml (>=6.0)、markdown (>=3.4)

• 可选（向量搜索）： sentence-transformers (>=3.0)、numpy (>=1.24)

许可证

有关详细信息，请参阅 LICENSE。