gramps-web-mcp

面向 Gramps Web 开源家谱平台的配套 MCP 服务器。它通过模型上下文协议（Model Context Protocol）为 AI 代理提供结构化、基于工具的家谱访问能力。

本项目不是独立的家谱用户界面或 Gramps Web 的替代品。请将其与现有的 Gramps Web 实例一起运行；您的用户、家谱、媒体、权限和家谱编辑界面仍保留在 Gramps Web 中。

功能特性

• 57 个 MCP 工具 — 读取、创建、更新和删除人物、家庭、事件、地点、来源、引文、笔记、媒体、仓库和标签

• 搜索与浏览 — 全文搜索和分页对象列表

• 亲属关系工具 — 祖先、后代、关系和时间线

• 复合工作流 — 快速添加人物、为人物添加事件、按 Gramps ID 查找

• 6 个 MCP 资源 — 类型词汇表、输入指南、家谱元数据、名称设置以及面向视觉能力代理的可选媒体缩略图/文件

• 媒体安全措施 — 大小限制、MIME 允许列表和私有记录默认设置

• MCP 提示 — 用于研究、添加人物/家庭和导入的引导式工作流

• 多种传输方式 — stdio（本地客户端）、Streamable HTTP、传统 SSE

• 只读模式 — 保持所有工具可见，同时阻止创建、更新和删除调用

请参阅工具目录获取完整列表。

Related MCP server: ASPNET Core Debugging MCP Server

前提条件

• .NET 8 SDK（用于本地开发）

• 一个正在运行的 Gramps Web 实例，具有 API 访问权限

• Docker（可选，用于容器部署）

快速开始

本地开发（演示服务器）

run-local-server.sh 使用已知的演示凭据（owner / owner）连接到公共 demo.grampsweb.org 实例：

./run-local-server.sh

服务器以 HTTP 传输方式启动，地址为 http://127.0.0.1:8080/mcp。仅绑定到回环地址时无需 API 密钥。

Docker

预构建的多架构镜像（linux/amd64、linux/arm64）已发布到 GitHub Container Registry。Docker 会自动选择匹配的架构；amd64 适用于大多数 Unraid 和 x86 主机，arm64 适用于 Apple Silicon 和 ARM SBC：

docker pull ghcr.io/scormave/gramps-web-mcp:latest

docker run -p 8080:8080 \
  -e GRAMPS_API_URL=https://your-gramps.example.com \
  -e GRAMPS_USERNAME=your-user \
  -e GRAMPS_PASSWORD=your-password \
  -e GRAMPS_TREE_ID=your-tree-uuid \
  -e MCP_API_KEY=your-secret-api-key \
  ghcr.io/scormave/gramps-web-mcp:latest

该镜像暴露了一个 GET /health 端点，用于 Docker HEALTHCHECK、Unraid 容器健康检查和其他运行时间监控。当 MCP 服务器能够通过 Gramps Web 进行身份验证时返回 HTTP 200，否则返回 HTTP 503。默认情况下，公共响应内容极简：{ "status": "healthy" } 或 { "status": "unhealthy" }。启动日志中包含一行类似 Connected to Gramps Web at … 的信息，表示 API 已可达。

镜像默认使用 Streamable HTTP（MCP_TRANSPORT=http）监听 8080 端口，上述命令即使用此方式。自行启动容器的客户端（如 MCP Registry 安装）则通过 stdio 运行，使用 -e MCP_TRANSPORT=stdio 并保持 stdin 打开（docker run -i）；这是 server.json 中声明的模式。

如需只读模式，添加 -e GRAMPS_READ_ONLY=true：

docker run -p 8080:8080 \
  -e GRAMPS_API_URL=https://your-gramps.example.com \
  -e GRAMPS_USERNAME=your-user \
  -e GRAMPS_PASSWORD=your-password \
  -e GRAMPS_TREE_ID=your-tree-uuid \
  -e MCP_API_KEY=your-secret-api-key \
  -e GRAMPS_READ_ONLY=true \
  ghcr.io/scormave/gramps-web-mcp:latest

Unraid 安装

Unraid 用户可以从 Community Applications 安装 gramps-web-mcp。模板源维护在 Scormave/gramps-web-mcp-unraid。有关 Unraid 特定的帮助，请参阅 Unraid 论坛上的支持帖子。

基本设置：

1. 在 Unraid 中，打开 Apps / Community Applications。

2. 搜索 gramps-web-mcp 并安装模板。

3. 为您的 Gramps Web 实例设置 GRAMPS_API_URL、GRAMPS_USERNAME、GRAMPS_PASSWORD 和 GRAMPS_TREE_ID。当 MCP 端口可从网络上的其他机器访问时，设置 MCP_API_KEY。

4. 保留默认容器端口 8080，或将其映射到其他主机端口。

5. 启动容器并检查 /health；一旦服务能够通过 Gramps Web 进行身份验证，它将返回 HTTP 200，默认返回极简 JSON 响应。

为获得最简单的配对体验，请将 Gramps Web 和 gramps-web-mcp 运行在同一个 Unraid Docker 网络上，并将 GRAMPS_API_URL 设置为 Gramps Web 容器 URL。客户端的 MCP 端点为 http://<unraid-host>:<mapped-port>/mcp。

Gramps Web + MCP（Docker Compose）

要在同一主机和 Docker 网络上运行 Gramps Web 和 MCP 服务器，请使用 docker-compose.example.yml 作为起点：

cp docker-compose.example.yml docker-compose.yml
cp .env.example .env
# Complete the Gramps Web setup wizard, then set credentials in .env
docker compose up -d

Gramps Web 发布在端口 5055 上；MCP 在 8080 上（/mcp 和 /health）。在 Compose 网络内部，MCP 容器通过 http://grampsweb:5000 访问 Gramps Web。

Claude Desktop（MCPB 扩展）

Claude Desktop 的一键安装可通过 MCP Bundle（.mcpb）从 GitHub Releases 获取。下载适用于您平台的 bundle：

1. 从最新版本下载适用于您操作系统的 .mcpb 文件。

2. 双击它，或将其拖入 Claude Desktop 窗口。

3. 输入您的 Gramps Web URL、用户名、密码/令牌和家谱 UUID。

4. 首次会话时保持启用只读模式；仅当您希望 Claude 创建或编辑记录时才禁用它。

5. 完成安装并开始新的聊天。

该扩展通过 stdio 在本地运行，不需要您的机器上安装 .NET SDK。 有关打包详情，请参阅 mcpb/README.md；有关隐私政策，请参阅 PRIVACY.md。

要在本地构建 bundle：

./scripts/pack-mcpb.sh osx-arm64   # or osx-x64, win-x64, linux-x64, linux-arm64

MCP 客户端配置（手动）

stdio（例如 Claude Desktop、Cursor）：

{
  "mcpServers": {
    "gramps-web": {
      "command": "dotnet",
      "args": ["run", "--project", "/path/to/gramps-web-mcp/GrampsWeb.Mcp/GrampsWeb.Mcp.csproj"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "GRAMPS_API_URL": "https://your-gramps.example.com",
        "GRAMPS_USERNAME": "your-user",
        "GRAMPS_PASSWORD": "your-password",
        "GRAMPS_TREE_ID": "your-tree-uuid"
      }
    }
  }
}

要以只读模式运行 stdio 服务器，请在 env 中添加 "GRAMPS_READ_ONLY": "true"。

HTTP（远程 / Docker）：

将您的 MCP 客户端指向 http://host:8080/mcp，使用 Streamable HTTP 传输。当设置了 MCP_API_KEY 时，在每个 MCP 请求中将其作为 Authorization: Bearer <key> 或 X-Api-Key: <key> 发送。

curl -X POST http://host:8080/mcp \
  -H "Authorization: Bearer $MCP_API_KEY" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}},"id":1}'

具有视觉能力的代理可以通过工具（GetMediaThumbnail、GetMediaFile）或二进制 MCP 资源（例如 gramps://media/{handle}/thumbnail/{size} 和 gramps://media/{handle}/file）读取可选的媒体。GetMediaFile 根据 MIME 类型返回图像、音频或嵌入式 blob 资源内容。端到端分析取决于 MCP 客户端是否将类型化工具内容或二进制资源内容转发给具有相应能力的模型。

配置

必需（Gramps 连接）

运行模式

• GRAMPS_READ_ONLY：设置为 true 以阻止创建、更新和删除调用，同时保持工具可见。

• GRAMPS_MUTATION_SERIALIZE：在此进程中一次只运行一个创建/更新/删除 HTTP 调用。

• GRAMPS_MUTATION_MIN_INTERVAL_MS：突变 HTTP 调用之间的最小暂停时间，包括复合工具内部的步骤。

运行说明：

• GRAMPS_READ_ONLY=false 表示服务器以读/写模式启动。

• Claude Desktop MCPB 扩展是个例外：其设置表单默认为只读，以确保首次使用更安全。

• 写入序列化和可选的间隔可保护典型的 Gramps Web SQLite 家谱免受代理写入突发的影响。

• 写入门控仅在进程内生效。它不会跨多个 MCP 副本、Gramps Web UI 或其他 API 客户端进行协调。

• 如果在顺序编辑时仍然遇到 database is locked 错误的 SQLite 部署，应将 GRAMPS_MUTATION_MIN_INTERVAL_MS 设置为 250 或 500。

• 当出现 SQLite 锁定错误或上游 HTTP 429 时，突变工具会返回一个可重试的 MCP 错误，并附带简短的回退提示，而不是通用的 500 错误。

• 当 Gramps Web 使用 PostgreSQL 且您希望并行写入时，请设置 GRAMPS_MUTATION_SERIALIZE=false。

媒体文件访问

媒体字节工具/资源默认禁用。get_media 仍然可用于获取元数据，而无需启用文件下载。

对于 AI 分析，建议优先使用 GetMediaThumbnail 或 gramps://media/{handle}/thumbnail/{size}。完整文件可能很大且敏感，并且仍受相同的大小、MIME 和私有记录检查约束。

支持精确类型和 type/* 通配符。默认媒体允许列表为 image/jpeg,image/png,image/webp,image/avif,application/pdf。

传输方式

照常设置 GRAMPS_API_URL、GRAMPS_USERNAME、GRAMPS_PASSWORD 和 GRAMPS_TREE_ID。

对于 HTTP 传输，响应通过 SSE 流式传输。有关协议详情，请参阅 Streamable HTTP 规范。设置 ASPNETCORE_URLS 以选择监听地址，例如 http://127.0.0.1:8080。

可选（MCP 传输）

HTTP 认证

当设置了 MCP_API_KEY 后，所有 MCP HTTP/SSE 端点每次请求都需要该密钥。 GET /health 保持匿名，供 Docker 和负载均衡器探测使用。

生成密钥：

openssl rand -base64 32

没有密钥时，服务器仍会启动（向后兼容）。如果监听地址不是仅限回环，则会记录一条警告，建议您设置 MCP_API_KEY、使用带有自身认证的反向代理，或绑定到 127.0.0.1 仅供本地使用。

在 Docker 内部，ASPNETCORE_URLS 通常为 http://0.0.0.0:8080，因此即使主机仅在 127.0.0.1 上发布端口，警告也会出现。当外部访问已受限时，这是预期行为。

开发

dotnet test

参见 CONTRIBUTING.md 和 开发者指南。

文档

贡献

欢迎贡献。参见 CONTRIBUTING.md。

安全

如需报告漏洞，请参见 SECURITY.md。

隐私政策

Claude Desktop 扩展是一个本地 MCP 服务器。它仅将数据发送给您配置的 Gramps Web 实例，不收集分析数据或对话数据。完整详情请参见 PRIVACY.md。

许可证

版权所有 (c) Scormave

本项目采用 GNU Affero General Public License v3.0（AGPL-3.0-or-later）许可。由于这是网络服务器软件，托管修改版本需要向通过网络与之交互的用户提供相应的源代码。