使用说明

父亲MCP

一种模型上下文协议服务器，通过文件优先搜索功能为AI助手提供对本地文档集合的直接访问。

特性

搜索功能

全文搜索 使用布尔运算符（AND、OR、NOT）和精确短语匹配
并行搜索 跨多个查询以获得更快的结果
模糊匹配 以及上下文感知的结果突出显示
由ugrep提供技术支持 -无需数据库或RAG基础设施

组织

分层集合 -使用文件夹结构组织知识
范围控制 -在集合内或特定文档中进行全局搜索
智能发现 -按名称或路径模式查找文档

格式支持

多种文档格式 -PDF、DOCX、HTML、JSON、XML等
自动格式检测 -无需手动配置
智能过滤器集成 -使用pandoc、jq和其他工具
优雅降级 -如果工具不可用，则格式自动禁用
看 docs/supported-formats.md 有关完整详细信息

安全

只读访问 -服务器从不修改您的文档
路径验证 -防止目录遍历攻击
命令沙盒 -筛选器命令在受限模式下运行
白名单执行 -执行前验证外壳过滤器

安装

来自PyPI（推荐）

直接从PyPI安装Fathom MCP：

pip install fathom-mcp

或者使用紫外线：

uv pip install fathom-mcp

系统相关性

此服务器需要以下系统实用程序：

# Ubuntu/Debian
sudo apt install ugrep poppler-utils

# macOS
brew install ugrep poppler

支持格式

Fathom MCP支持搜索和阅读多种文档格式：

默认格式（不需要其他工具）

标记语言 （.md，.markdown）
纯文本 （.txt、.rst）
CSV文件 （.csv）
PDF （.pdf）-需要pdftotext（来自poppler-utils）

可选格式（需要外部工具）

微软Word （.doc，.docx）-需要pandoc或antiford
开放文档格式 （.odt）-需要pandoc
电子版 （.epub）-需要pandoc
超文本标记语言 （.html、.htm）-需要pandoc
RTF格式 （.rtf）-需要pandoc
JSON （.json）-需要使用jq
可扩展标记语言 （.xml）-需要pandoc

可选格式的快速设置

要启用所有可选格式：

# macOS
brew install pandoc jq

# Linux (Ubuntu/Debian)
sudo apt install pandoc jq

# Windows (Chocolatey)
choco install pandoc jq

看 docs/supported-formats.md 有关详细的安装说明、配置选项和故障排除。

收藏和范围

文件知识服务器使用 基于集合的层次结构 它直接映射到您的文件系统结构。

了解收藏

A. 收集只是知识库根目录中的一个文件夹
集合可以嵌套到任何深度
每个文档只属于一个集合（其包含文件夹）
根目录本身是顶级集合

配置知识根

知识根可以通过以下方式指定：

命令行参数 （建议用于静态设置）：

fathom-mcp --root /path/to/documents

配置文件:

knowledge:
  root: "/path/to/documents"

环境变量:

export FMCP_KNOWLEDGE__ROOT=/path/to/documents

搜索范围

所有搜索操作都支持三个范围级别：

全局范围 -搜索知识库中的所有文档
收集范围 -将搜索限制到特定文件夹及其子文件夹
文件范围 -仅在单个文档中搜索

这种分层方法实现了高效的知识组织，而不需要数据库基础设施。

配置

基本配置

创建一个 config.yaml 使用您的设置：

knowledge:
  root: "./documents"

search:
  context_lines: 5        # Lines of context around matches
  max_results: 50         # Maximum results per search
  timeout: 30             # Search timeout in seconds

security:
  enable_shell_filters: true
  filter_mode: whitelist  # Recommended for production

exclude:
  patterns:
    - ".git/*"
    - "*.draft.*"
    - "*.tmp"

看 config.example.yaml 所有可用选项。

环境变量

所有配置选项都可以使用环境变量覆盖 FMCP_ 前缀：

export FMCP_KNOWLEDGE__ROOT=/path/to/documents
export FMCP_SEARCH__MAX_RESULTS=100
export FMCP_SECURITY__FILTER_MODE=whitelist

使用双下划线(__)表示嵌套的配置级别。

API

工具

服务器实现了六个MCP工具，分为三类：

浏览操作

list_collections -列出集合中的文件夹和文档
find_document -按名称或路径模式查找文档

搜索操作

search_documents -使用布尔运算符进行全文搜索
search_multiple -并行执行多个搜索

读取操作

read_document -使用可选页面选择读取文档内容
get_document_info -获取文档元数据和目录

list_collections

浏览知识库的层次结构。

论据：

path （字符串，可选）：相对于根的集合路径。默认为根级别。

退货：

子集合（文件夹）列表
文档及其路径和格式列表

例子：

{
  "path": "programming/python"
}

find_document

使用模糊匹配按文件名或路径模式定位文档。

论据：

query （字符串，必填）：文档名称的搜索词
limit （数字，可选）：返回的最大结果数（默认值：20）

退货：

具有路径和相关性得分的匹配文档列表

例子：

{
  "query": "async patterns",
  "limit": 10
}

搜索文档

使用强大的布尔运算符在知识库中执行全文搜索。

论据：

query （字符串，必填）：使用可选运算符的搜索查询
scope （对象，必填）：定义搜索边界
- type （string）：其中之一 "global", "collection"，或 "document"
- path （字符串，条件）：必填 collection 和 document 范围

搜索操作员：

term1 term2 -AND：查找同时包含这两个术语的文档
term1|term2 -OR：查找包含任一术语的文档
term1 -term2 -否：排除包含term2的文档
"exact phrase" -将精确短语与引号匹配

退货：

与文档路径、行号和上下文匹配的列表
如果结果超过最大值，则显示截断指示器

示例：

全局搜索：

{
  "query": "authentication jwt",
  "scope": {
    "type": "global"
  }
}

集合范围搜索：

{
  "query": "async|await -deprecated",
  "scope": {
    "type": "collection",
    "path": "programming/python"
  }
}

文档特定搜索：

{
  "query": "\"error handling\"",
  "scope": {
    "type": "document",
    "path": "guides/best-practices.md"
  }
}

搜索_倍数

同时执行多个搜索查询以提高性能。

论据：

queries （字符串数组，必填）：搜索查询列表
scope （object，必填）：范围结构与 search_documents

退货：

将每个查询映射到其搜索结果的对象
每个结果都包括匹配和截断状态

例子：

{
  "queries": ["authentication", "authorization", "session management"],
  "scope": {
    "type": "collection",
    "path": "security/docs"
  }
}

注：并发搜索受到以下因素的限制 limits.max_concurrent_searches 配置设置。

read_文档

通过可选的PDF页面选择阅读文档的完整内容。

论据：

path （字符串，必填）：相对于知识根的文档路径
pages （数字数组，可选）：要阅读的特定页面（仅限PDF）

退货：

文档内容为文本
格式化元数据

示例：

阅读整个文档：

{
  "path": "guides/user-manual.pdf"
}

阅读特定页面：

{
  "path": "guides/user-manual.pdf",
  "pages": [1, 5, 10]
}

注：内容长度受限制 limits.max_read_chars 配置设置。

get_document_info

检索文档的元数据和结构信息。

论据：

path （字符串，必填）：相对于知识根的文档路径

退货：

文件大小和格式
页数（PDF）
带页码的目录（如有）
上次修改时间戳

例子：

{
  "path": "reference/api-documentation.pdf"
}

使用Claude Desktop

使用命令行参数

将此添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "fathom-mcp": {
      "command": "fathom-mcp",
      "args": ["--root", "/path/to/your/documents"]
    }
  }
}

使用配置文件

对于更复杂的设置，请使用配置文件：

{
  "mcpServers": {
    "fathom-mcp": {
      "command": "fathom-mcp",
      "args": ["--config", "/path/to/config.yaml"]
    }
  }
}

使用紫外线（显影）

从源代码开发或运行时：

{
  "mcpServers": {
    "fathom-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/fathom-mcp",
        "run",
        "fathom-mcp",
        "--root",
        "/path/to/documents"
      ]
    }
  }
}

配置文件位置

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
视窗: %APPDATA%/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

重要提示： 修改配置文件后重新启动Claude Desktop。

HTTP传输支持

Fathom MCP支持两种用于不同部署场景的传输协议：

1.标准运输（默认）

对于Claude Desktop集成，服务器通过标准输入/输出进行通信：

{
  "mcpServers": {
    "fathom-mcp": {
      "command": "fathom-mcp",
      "args": ["--root", "/path/to/your/documents"]
    }
  }
}

Docker（可选）：

# Run stdio transport in Docker
docker compose --profile stdio up

2.HTTP传输（Docker）

对于远程部署和web客户端，服务器作为HTTP服务运行。

流式HTTP：

# Start server
docker compose --profile http up fathom-mcp-http

# Test connectivity
fathom-mcp-test -t streamable-http -u http://localhost:8765/mcp -l basic

配置

通过环境变量或配置文件配置的HTTP传输：

环境变量：

export FMCP_TRANSPORT__TYPE=streamable-http
export FMCP_TRANSPORT__HOST=0.0.0.0
export FMCP_TRANSPORT__PORT=8765
export FMCP_TRANSPORT__ENABLE_CORS=true
export FMCP_TRANSPORT__ALLOWED_ORIGINS='["https://app.example.com"]'

配置文件：

transport:
  type: "streamable-http"
  host: "0.0.0.0"
  port: 8765
  enable_cors: true
  allowed_origins:
    - "https://app.example.com"
  structured_logging: true

安全

⚠️ 重要提示：无内置身份验证

Fathom MCP不包括HTTP传输的身份验证。 这是有意的——身份验证应该由专用工具处理。

对于HTTP部署：

✅ 使用反向代理 （Nginx、Caddy、Traefik）具有身份验证功能
✅ 使用VPN （Tailscale、WireGuard）用于网络隔离
✅ 使用HTTPS 在生产环境中（从不使用HTTP）
❌ 永远不要暴露 直接通过HTTP传输到互联网
❌ 切勿使用 通配符CORS(*)生产中

供本地使用： 使用默认值 stdio 传输-无需网络访问，无需身份验证。

看 docs/security.md 有关详细的安全设置，请参阅反向代理、VPN和OAuth的示例。

测试

测试客户端可用于所有传输：

# Connectivity test
fathom-mcp-test -t streamable-http -u http://localhost:8765/mcp -l connectivity

# Basic test suite
fathom-mcp-test -t streamable-http -u http://localhost:8765/mcp -l basic

# Full test suite with verbose output
fathom-mcp-test -t streamable-http -u http://localhost:8765/mcp -l full -v

退出代码：

0:所有测试均已通过
1：部分测试失败
2：严重错误（无法连接）
3：配置错误
4：超时错误
6：部分成功（连接正常，工具失败）

Docker部署

使用docker compose（推荐）

# Start the server
docker-compose up

# Build and start
docker-compose up --build

# Run in detached mode
docker-compose up -d

包括 docker-compose.yaml 提供：

为安全起见，只读文档挂载
资源限制（512MB内存，1个CPU）
MCP协议的正确stdio配置

手动Docker构建

# Build image
docker build -t fathom-mcp .

# Run with read-only mount
docker run -v /path/to/docs:/knowledge:ro fathom-mcp

# Run with custom configuration
docker run \
  -v /path/to/docs:/knowledge:ro \
  -v /path/to/config.yaml:/config/config.yaml:ro \
  fathom-mcp

云存储集成

文件知识服务器在以下平台上运行 仅限本地文件为了安全和架构清晰，云同步是在MCP服务器之外有意处理的。

发展

项目设置

# Clone repository
git clone https://github.com/RomanShnurov/fathom-mcp
cd fathom-mcp

# Install with development dependencies (recommended)
uv sync --extra dev

# Alternative: pip
pip install -e ".[dev]"

运行测试

# Run all tests
uv run pytest

# Run with coverage report
uv run pytest --cov

# Run specific test file
uv run pytest tests/test_search.py

# Run with verbose output
uv run pytest -v

代码质量工具

# Format code
uv run ruff format .

# Lint code
uv run ruff check .

# Auto-fix linting issues
uv run ruff check . --fix

# Type checking
uv run mypy src

安全

文件知识服务器实现了深度防御安全。

传输安全

⚠️ HTTP传输安全： 使用HTTP传输时(streamable-http)，服务器不包括内置身份验证。这是有意的——使用外部工具：

反向代理 （Nginx、Caddy、Traefik）具有基本身份验证或OAuth
虚拟专用网络 （Tailscale、WireGuard）用于网络隔离
仅限本地主机 (host: 127.0.0.1)用于同一台机器访问
stdio传输 （默认）用于本地AI代理，如Claude Desktop

📖 看 docs/security.md 查看完整的设置指南和配置示例。

路径安全

路径验证：根据知识根验证所有文件路径
横向预防：块 ../ 以及绝对路径攻击
Symlink政策：可配置符号链接如下（默认：禁用）

指挥安全

白名单执行：执行前已验证筛选命令
沙盒执行：Shell命令在有超时限制的情况下运行
只读设计：服务器从不修改文档集合
无凭据访问：服务器从不接触云存储API

配置

security:
  enable_shell_filters: true
  filter_mode: whitelist          # Recommended for production
  allowed_filter_commands:
    - "pdftotext % -"
  symlink_policy: disallow        # Prevent symlink attacks

对于生产HTTP部署，始终使用反向代理或VPN。看 docs/security.md.

调试

由于MCP服务器在stdio上运行，调试可能具有挑战性。Fathom MCP提供了两种交互式测试选项。

内置MCP检查器（推荐）

Fathom MCP包括一个基于Streamlit的检查器UI，用于测试服务器工具、资源和提示：

# Install inspector dependencies
uv sync --extra inspector

# Run the inspector
streamlit run inspector/app.py

内置检查器提供：

使用动态表单进行交互式工具测试
资源浏览和内容阅读
及时上市和检查
具有过滤功能的实时服务器日志
无外部依赖（不需要Node.js）

外部MCP检查员

或者，使用官方 MCP检查员:

npx @modelcontextprotocol/inspector fathom-mcp --root /path/to/documents

您还可以将其与配置文件一起使用：

npx @modelcontextprotocol/inspector fathom-mcp --config config.yaml

贡献

欢迎投稿！拜托：

分叉存储库
创建要素分支
通过测试进行更改
运行代码质量检查(ruff format, ruff check, mypy)
提交拉取请求

看 CONTRIBUTING.md 详细指南。

许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

资源

文档

安全指南 -反向代理、VPN和OAuth设置
支持格式 -文档格式配置
云同步指南 -云存储集成
集成指南 -客户端设置和部署
配置参考 -所有配置选项
工具参考 -完整的MCP工具文档

外部资源

模型上下文协议 -MCP官方文件
MCP规范 -协议规范
ugrep -具有布尔搜索的超快速grep
poppler-utils -PDF渲染工具

使用说明

父亲MCP

特性

搜索功能

组织

格式支持

安全

安装

来自PyPI（推荐）

系统相关性

支持格式

默认格式（不需要其他工具）

可选格式（需要外部工具）

可选格式的快速设置

收藏和范围

了解收藏

配置知识根

搜索范围

配置

基本配置

环境变量

API

工具

浏览操作

搜索操作

读取操作

list_collections

find_document

搜索文档

搜索_倍数

read_文档

get_document_info

使用Claude Desktop

使用命令行参数

使用配置文件

使用紫外线（显影）

配置文件位置

HTTP传输支持

1.标准运输（默认）

2.HTTP传输（Docker）

流式HTTP：

配置

安全

测试

Docker部署

使用docker compose（推荐）

手动Docker构建

云存储集成

推荐方法

发展

项目设置

运行测试

代码质量工具

安全

传输安全

路径安全

指挥安全

配置

调试

内置MCP检查器（推荐）

外部MCP检查员

贡献

许可证

资源

文档

外部资源

相关 MCP

开源嵌入数据库

Zotero MCP服务

文档管理服务

macOS通知服务

任务与记忆管理服务器

知识库存储服务