Gramps Web MCP

gramps-web-mcp

警告

请升级到 2.3.1 或更高版本。 在 2.3.1 之前，update_* 工具可能会丢弃调用中未提及的 已存储数据 (#5)。如果你使用较早版本编辑过 族谱， 请检查是否有数据被丢弃。

这是 Gramps Web 开源族谱平台的配套 MCP 服务。它通过模型上下文协议，为 AI Agent 提供以结构化工具访问族谱的能力。

本项目不是独立的族谱界面，也不能替代 Gramps Web。请将它与现有的 Gramps Web 实例一同运行；用户、族谱、媒体、权限和族谱编辑界面仍由 Gramps Web 管理。

[][install-vscode] [][install-vscode-insiders] [][install-cursor]

这些按钮会将服务添加到 VS Code 或 Cursor，并从 Docker 镜像启动它，因此必须安装 Docker。详情请参阅 通过 Docker 使用 stdio；对于 Claude Desktop，请安装 MCPB 扩展。

功能

• 最多支持 32 个 MCP 工具 — 读取、创建、更新和删除人物、家庭、事件、地点、 来源、引文、笔记、媒体、知识库和标签
• 搜索与浏览 — 全文搜索和分页对象列表， 可按 Gramps QL 或 Gramps 筛选规则进行筛选（与某人有关的所有人、没有家庭关联的人）
• 亲属关系工具 — 祖先、后代、关系和时间线
• 增量链接 — 使用 linkMode 添加或移除单个事件、子女、引文或笔记， 同时保留其他所有链接
• 撤销 — 撤销编辑历史中的一项事务，包括删除操作；执行前会检查是否会覆盖后续编辑或破坏链接
• 确认对话框 — 在支持 MCP elicitation 的客户端中，delete_object 和 undo_change 会先向用户（而非模型）请求确认，再更改家谱树
• 按 Gramps 的方式处理日期 — 范围日期、之前／之后／约，以及所有 Gramps 日历（1856-07-20 (Julian)）；并保存 Gramps 计算出的排序值
• 8 个 MCP 资源 — 类型词汇表、输入指南、家谱树元数据、姓名设置、筛选规则，以及供具备视觉能力的 Agent 选择启用的媒体预览／文件
• 媒体保护措施 — 大小限制、默认保护私人记录，并剥除预览中的 EXIF／GPS 元数据
• MCP 提示词 — 为研究、发现关联、添加人物／家庭、导入、更改链接和引用事实提供引导式工作流
• 多种传输方式 — stdio（本地客户端）、Streamable HTTP、旧版 SSE
• 只读模式 — 仅发布读取工具，并阻止直接修改调用

完整列表请参阅工具目录。 从 1.x 升级？请按照2.0 迁移指南 更新已保存的工具调用和客户端设置。

所有发往 Gramps Web 的请求（包括身份验证、媒体下载和健康检查）都会自动使用以下标识此应用： User-Agent: gramps-web-mcp/<version> (+https://github.com/Scormave/gramps-web-mcp)。 版本号来自应用构建，无需配置。

先决条件

• .NET 10 SDK（用于本地开发）
• 正在运行且可访问 API 的 Gramps Web 实例
• 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 单板计算机：

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

若要使用刷新令牌进行身份验证，请将 GRAMPS_USERNAME 和 GRAMPS_PASSWORD 两行替换为 -e GRAMPS_REFRESH_TOKEN=your-refresh-token。

每个已发布的镜像都有一份构建来源证明：由 GitHub 保留在 GitHub 和注册表中的签名记录，记录了构建该镜像的仓库、工作流和提交。 使用 GitHub CLI 检查镜像是否由此仓库的 GitHub Actions 构建（如果已安装 Docker Desktop，请先启动它：gh 会向其请求注册表凭据）：

gh attestation verify oci://ghcr.io/scormave/gramps-web-mcp:latest --repo Scormave/gramps-web-mcp

该镜像提供 GET /health 端点，用于 Docker HEALTHCHECK、Unraid 容器健康状态检查及其他运行时间监控工具。当 MCP 服务能够通过身份验证连接到 Gramps Web 时，该端点返回 HTTP 200；否则返回 HTTP 503。探测会重用工具所使用的令牌，因此不会每次都登录 Gramps Web。公开响应内容精简：{ "status": "healthy" } 或 { "status": "unhealthy" }。API 可访问后，启动日志中会出现类似 Connected to Gramps Web at … 的一行。

该镜像基于 Ubuntu Chiseled 构建，不包含 shell 或 curl。其 HEALTHCHECK 会运行 dotnet /app/GrampsWeb.Mcp.dll --health-check，向 ASPNETCORE_URLS 指定端口上的 /health 发起请求，并在收到 HTTP 200 时以 0 退出，否则以 1 退出。在 Compose 或 NAS 应用模板中自行定义的健康检查也会运行同一命令：

healthcheck:
  test: ["CMD", "dotnet", "/app/GrampsWeb.Mcp.dll", "--health-check"]

如果服务监听的地址未由 ASPNETCORE_URLS 指定，请在选项后传入 URL，例如 --health-check http://localhost:9000。

镜像默认使用 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_TREE_ID，以及 GRAMPS_USERNAME 和 GRAMPS_PASSWORD，或 GRAMPS_REFRESH_TOKEN。如果网络中的其他机器可以访问 MCP 端口，请设置 MCP_API_KEY。
4. 保持默认容器端口 8080，或将其映射到其他主机端口。
5. 启动容器并检查 /health；服务通过身份验证连接到 Gramps Web 后，该端点会返回 HTTP 200 以及精简的 JSON 响应。

如需最简单的连接方式，请在同一个 Unraid Docker 网络上运行 Gramps Web 和 gramps-web-mcp，并将 GRAMPS_API_URL 设置为 Gramps Web 容器 URL。客户端使用的 MCP 端点为 http://<unraid-host>:<mapped-port>/mcp；连接方式请参阅其他 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 an authentication method in .env
docker compose up -d

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

Claude Desktop（MCPB 扩展）

可从 GitHub Releases 一键安装 Claude Desktop 的 MCP Bundle（.mcpb）。下载适用于你平台的安装包：

平台	安装包
macOS Apple Silicon	gramps-web-mcp-claude-desktop-osx-arm64-v*.mcpb
macOS Intel	gramps-web-mcp-claude-desktop-osx-x64-v*.mcpb
Windows x64	gramps-web-mcp-claude-desktop-win-x64-v*.mcpb
Linux x64	gramps-web-mcp-claude-desktop-linux-x64-v*.mcpb
Linux ARM64	gramps-web-mcp-claude-desktop-linux-arm64-v*.mcpb

1. 从最新版本中下载适用于你操作系统的 .mcpb 文件。
2. 双击该文件，或将其拖入 Claude Desktop 窗口。
3. 输入 Gramps Web URL、用户名、密码/令牌和树 UUID。
4. 首次会话时保持启用 只读模式；仅当你希望 Claude 创建或编辑记录时才将其关闭。
5. 完成安装并开始新聊天。

该扩展通过 stdio 在本地运行，且不需要在你的计算机上安装 .NET SDK。如需确认下载的安装包来自此仓库，请参阅发行版二进制文件下方的认证说明。 有关打包详情，请参阅 mcpb/README.md；有关隐私政策，请参阅 PRIVACY.md。

在本地构建安装包：

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

其他 MCP 客户端

其他 MCP 客户端（例如 Claude Code、VS Code、Cursor、Codex、Antigravity CLI 和 Open WebUI）可通过以下三种方式之一连接：

• 通过 HTTP 连接到已在 Docker、Unraid 或 Docker Compose 中运行的服务。每个客户端只需服务地址和 API 密钥，无需在客户端计算机上安装任何内容，且所有客户端共用同一个服务。
• 通过 Docker 使用 stdio：客户端为自身启动服务镜像。每台计算机都需要安装 Docker 并提供 Gramps Web 凭据。VS Code 和 Cursor 可一键完成此设置。
• 通过发行版二进制文件使用 stdio：客户端通过从发行版下载的单个文件启动服务。每台计算机都需要 Gramps Web 凭据，但不需要 Docker 或 .NET。

Claude Desktop 通过 Anthropic 的云端连接以 URL 添加的服务，而不是从你的计算机连接，因此无法访问家庭网络上的服务。请在此处使用 MCPB 扩展。

通过 HTTP

在服务端设置 MCP_API_KEY（参见 HTTP 身份验证）， 然后向每个客户端提供地址和密钥。示例使用 http://192.168.1.10:8080/mcp 和 your-secret-api-key；请将两者替换为 你自己的值。

Claude Code：

claude mcp add --transport http --scope user gramps-web http://192.168.1.10:8080/mcp \
  --header "Authorization: Bearer your-secret-api-key"

VS Code，在用户级 mcp.json 或工作区的 .vscode/mcp.json 中配置。服务器 首次启动时，VS Code 会提示输入密钥：

{
  "inputs": [
    {
      "type": "promptString",
      "id": "gramps-web-mcp-key",
      "description": "Gramps Web MCP API key",
      "password": true
    }
  ],
  "servers": {
    "gramps-web": {
      "type": "http",
      "url": "http://192.168.1.10:8080/mcp",
      "headers": { "Authorization": "Bearer ${input:gramps-web-mcp-key}" }
    }
  }
}

Cursor，在 ~/.cursor/mcp.json 中配置：

{
  "mcpServers": {
    "gramps-web": {
      "url": "http://192.168.1.10:8080/mcp",
      "headers": { "Authorization": "Bearer your-secret-api-key" }
    }
  }
}

Codex，在 ~/.codex/config.toml 中配置。Codex 会从 bearer_token_env_var 指定的环境变量中读取密钥，因此请在启动前设置 GRAMPS_WEB_MCP_KEY：

[mcp_servers.gramps-web]
url = "http://192.168.1.10:8080/mcp"
bearer_token_env_var = "GRAMPS_WEB_MCP_KEY"

Antigravity CLI，在 ~/.gemini/config/mcp_config.json 中配置。Gemini CLI 使用相同的配置项，但放在 ~/.gemini/settings.json 中，并以 httpUrl 替代 serverUrl：

{
  "mcpServers": {
    "gramps-web": {
      "serverUrl": "http://192.168.1.10:8080/mcp",
      "headers": { "Authorization": "Bearer your-secret-api-key" }
    }
  }
}

Open WebUI 0.6.31 或更高版本：管理员打开 Settings → Admin → Integrations，然后在 External Tool Servers 下添加一个类型为 MCP (Streamable HTTP) 的连接，填写服务 URL，将身份验证方式设为 Bearer， 并在 Key 中填写 API 密钥。Open WebUI 会从自己的容器发起连接，此时 localhost 指向该容器：请使用主机地址；如果两个容器共享 Docker 网络，也可以使用 MCP 容器的名称。

请注意：

• 普通 HTTP 不会加密密钥和树数据。请将端口限制在可信网络内，并从其他网络通过 VPN 连接，而不要将端口公开到互联网上。
• Cursor 和 Antigravity CLI 的配置文件中保存了密钥本身，请勿将它们放入 项目代码库。
• 每个客户端都以服务端所配置的 Gramps Web 账户身份运行，Gramps Web 会将它们的所有编辑记录在该账户下。
• 通过默认的无状态 HTTP 连接时，delete_object 和 undo_change 无法显示确认对话框；请参见 确认删除和撤销。

如需在终端中检查地址和密钥，请发送一个 initialize 请求。 密钥也可通过 X-Api-Key: <key> 发送：

curl -X POST http://192.168.1.10: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}'

在 Docker 中通过 stdio 连接

客户端会为每个会话启动一个容器，并在会话结束时将其删除。必须设置 MCP_TRANSPORT=stdio，因为镜像默认使用 HTTP；不带值的 -e NAME 会将 env 中的变量传递给容器，因此密码不会出现在 docker 命令行中：

{
  "mcpServers": {
    "gramps-web": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT=stdio",
        "-e", "GRAMPS_API_URL",
        "-e", "GRAMPS_USERNAME",
        "-e", "GRAMPS_PASSWORD",
        "-e", "GRAMPS_TREE_ID",
        "ghcr.io/scormave/gramps-web-mcp:latest"
      ],
      "env": {
        "GRAMPS_API_URL": "https://your-gramps.example.com",
        "GRAMPS_USERNAME": "your-user",
        "GRAMPS_PASSWORD": "your-password",
        "GRAMPS_TREE_ID": "your-tree-uuid"
      }
    }
  }
}

本 README 顶部的安装按钮会将此配置项添加到 VS Code 或 Cursor。服务器首次启动时，VS Code 会提示输入 Gramps Web 地址、用户名、 密码和树 ID，并将密码保存在其安全存储中。Cursor 会添加上面显示的占位符； 首次启动前请将它们替换为你自己的值。 [install-vscode]: https://insiders.vscode.dev/redirect/mcp/install?name=gramps-web&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22gramps-web-api-url%22%2C%22description%22%3A%22Gramps%20Web%20address%2C%20such%20as%20https%3A%2F%2Fyour-gramps.example.com%22%7D%2C%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22gramps-web-username%22%2C%22description%22%3A%22Gramps%20Web%20user%20name%22%7D%2C%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22gramps-web-password%22%2C%22description%22%3A%22Gramps%20Web%20password%22%2C%22password%22%3Atrue%7D%2C%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22gramps-web-tree-id%22%2C%22description%22%3A%22Gramps%20Web%20tree%20ID%22%7D%5D&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-i%22%2C%22--rm%22%2C%22-e%22%2C%22MCP_TRANSPORT%3Dstdio%22%2C%22-e%22%2C%22GRAMPS_API_URL%22%2C%22-e%22%2C%22GRAMPS_USERNAME%22%2C%22-e%22%2C%22GRAMPS_PASSWORD%22%2C%22-e%22%2C%22GRAMPS_TREE_ID%22%2C%22ghcr.io%2Fscormave%2Fgramps-web-mcp%3Alatest%22%5D%2C%22env%22%3A%7B%22GRAMPS_API_URL%22%3A%22%24%7Binput%3Agramps-web-api-url%7D%22%2C%22GRAMPS_USERNAME%22%3A%22%24%7Binput%3Agramps-web-username%7D%22%2C%22GRAMPS_PASSWORD%22%3A%22%24%7Binput%3Agramps-web-password%7D%22%2C%22GRAMPS_TREE_ID%22%3A%22%24%7Binput%3Agramps-web-tree-id%7D%22%7D%7D [install-vscode-insiders]: https://insiders.vscode.dev/redirect/mcp/install?name=gramps-web&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22gramps-web-api-url%22%2C%22description%22%3A%22Gramps%20Web%20address%2C%20such%20as%20https%3A%2F%2Fyour-gramps.example.com%22%7D%2C%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22gramps-web-username%22%2C%22description%22%3A%22Gramps%20Web%20user%20name%22%7D%2C%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22gramps-web-password%22%2C%22description%22%3A%22Gramps%20Web%20password%22%2C%22password%22%3Atrue%7D%2C%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22gramps-web-tree-id%22%2C%22description%22%3A%22Gramps%20Web%20tree%20ID%22%7D%5D&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-i%22%2C%22--rm%22%2C%22-e%22%2C%22MCP_TRANSPORT%3Dstdio%22%2C%22-e%22%2C%22GRAMPS_API_URL%22%2C%22-e%22%2C%22GRAMPS_USERNAME%22%2C%22-e%22%2C%22GRAMPS_PASSWORD%22%2C%22-e%22%2C%22GRAMPS_TREE_ID%22%2C%22ghcr.io%2Fscormave%2Fgramps-web-mcp%3Alatest%22%5D%2C%22env%22%3A%7B%22GRAMPS_API_URL%22%3A%22%24%7Binput%3Agramps-web-api-url%7D%22%2C%22GRAMPS_USERNAME%22%3A%22%24%7Binput%3Agramps-web-username%7D%22%2C%22GRAMPS_PASSWORD%22%3A%22%24%7Binput%3Agramps-web-password%7D%22%2C%22GRAMPS_TREE_ID%22%3A%22%24%7Binput%3Agramps-web-tree-id%7D%22%7D%7D&quality=insiders [install-cursor]: https://cursor.com/en/install-mcp?name=gramps-web&config=eyJjb21tYW5kIjoiZG9ja2VyIiwiYXJncyI6WyJydW4iLCItaSIsIi0tcm0iLCItZSIsIk1DUF9UUkFOU1BPUlQ9c3RkaW8iLCItZSIsIkdSQU1QU19BUElfVVJMIiwiLWUiLCJHUkFNUFNfVVNFUk5BTUUiLCItZSIsIkdSQU1QU19QQVNTV09SRCIsIi1lIiwiR1JBTVBTX1RSRUVfSUQiLCJnaGNyLmlvL3Njb3JtYXZlL2dyYW1wcy13ZWItbWNwOmxhdGVzdCJdLCJlbnYiOnsiR1JBTVBTX0FQSV9VUkwiOiJodHRwczovL3lvdXItZ3JhbXBzLmV4YW1wbGUuY29tIiwiR1JBTVBTX1VTRVJOQU1FIjoieW91ci11c2VyIiwiR1JBTVBTX1BBU1NXT1JEIjoieW91ci1wYXNzd29yZCIsIkdSQU1QU19UUkVFX0lEIjoieW91ci10cmVlLXV1aWQifX0%3D

• Cursor（~/.cursor/mcp.json）、Antigravity CLI （~/.gemini/config/mcp_config.json）和 Gemini CLI （~/.gemini/settings.json）可直接使用此条目。
• Claude Code：将 gramps-web 对象传递给 claude mcp add-json --scope user gramps-web '<object>'。
• VS Code：将条目放在 servers 下，而不是 mcpServers 下，并添加 "type": "stdio"。
• Codex：在 ~/.codex/config.toml 的 [mcp_servers.gramps-web] 下放置相同的 command、args 和 env。
• Open WebUI 仅通过 HTTP 连接。

首次启动前：

• 使用 docker pull ghcr.io/scormave/gramps-web-mcp:latest 拉取一次镜像。 有些客户端只给服务几秒钟启动时间，不足以完成下载。
• 在容器内，localhost 指的是容器本身。如果 Gramps Web 运行在同一台计算机上，请在 GRAMPS_API_URL 中使用 host.docker.internal；在 Linux 上，还要将 "--add-host=host.docker.internal:host-gateway" 添加到 args。
• 若要使用刷新令牌，请在两个列表中将 GRAMPS_USERNAME 和 GRAMPS_PASSWORD 替换为 GRAMPS_REFRESH_TOKEN。若要启用只读模式，请在镜像名称前添加 "-e", "GRAMPS_READ_ONLY=true"；其他 设置也采用相同方式。
• 上传会读取容器内的文件，因此请使用 -v 挂载 上传文件夹。

使用发布版二进制文件通过 stdio 通信

每个发布版本都包含一个独立的服务文件，Claude Desktop 捆绑包中也包含同一个文件。除非另有指定，否则它会通过 stdio 启动：

平台	压缩包
macOS Apple Silicon	gramps-web-mcp-osx-arm64.tar.gz
macOS Intel	gramps-web-mcp-osx-x64.tar.gz
Windows x64	gramps-web-mcp-win-x64.zip
Linux x64	gramps-web-mcp-linux-x64.tar.gz
Linux ARM64	gramps-web-mcp-linux-arm64.tar.gz

将适用于你平台的压缩包解压到单独的文件夹中。在 macOS 或 Linux 上（此处以 Apple Silicon 为例；请将压缩包名称替换为对应文件）：

mkdir -p ~/.local/share/gramps-web-mcp
curl -fL https://github.com/Scormave/gramps-web-mcp/releases/latest/download/gramps-web-mcp-osx-arm64.tar.gz \
  | tar -xz -C ~/.local/share/gramps-web-mcp

在 Windows 上，使用 PowerShell：

curl.exe -fLo "$env:TEMP\gramps-web-mcp.zip" https://github.com/Scormave/gramps-web-mcp/releases/latest/download/gramps-web-mcp-win-x64.zip
Expand-Archive -Force "$env:TEMP\gramps-web-mcp.zip" "$env:LOCALAPPDATA\gramps-web-mcp"

然后使用二进制文件的完整路径指定客户端，因为客户端启动时不会使用能够展开 ~ 的 shell：

{
  "mcpServers": {
    "gramps-web": {
      "command": "/Users/you/.local/share/gramps-web-mcp/GrampsWeb.Mcp",
      "env": {
        "GRAMPS_API_URL": "https://your-gramps.example.com",
        "GRAMPS_USERNAME": "your-user",
        "GRAMPS_PASSWORD": "your-password",
        "GRAMPS_TREE_ID": "your-tree-uuid"
      }
    }
  }
}

在 Windows 上，command 为 "C:\\Users\\you\\AppData\\Local\\gramps-web-mcp\\GrampsWeb.Mcp.exe"：JSON 要求将每个反斜杠加倍。每个客户端都以与上文 Docker 配置相同的方式使用此条目。

• 每项设置都是 env 中的环境变量，例如使用 GRAMPS_REFRESH_TOKEN 代替用户名和密码，或设置 "GRAMPS_READ_ONLY": "true"。与 Docker 不同，GRAMPS_API_URL 中的 localhost 以及 上传文件夹指的是你自己的计算机。
• 要更新，请关闭客户端（Windows 无法替换正在运行的二进制文件），再次运行相同的命令，然后启动客户端：压缩包名称不包含版本号，因此链接始终会获取最新发布版本，新二进制文件会替换旧文件。
• 该二进制文件未经过 Apple 公证。curl 不会为下载内容添加标记，因此 macOS 可以运行它；如果你通过浏览器下载了压缩包，macOS 可能会拒绝启动该二进制文件，除非你使用 xattr -d com.apple.quarantine ~/.local/share/gramps-web-mcp/GrampsWeb.Mcp 移除标记。
• 在 Linux 上，它需要 glibc 和 ICU（libicu），桌面发行版都包含这些库；在 Alpine 或精简系统上，请使用 Docker。
• 每个发布版本中的 SHA256SUMS 都列出了其中各文件的校验和，每个文件（包括捆绑包）都有构建来源证明。要验证下载内容，请保存压缩包，而不要将其通过管道传给 tar，然后使用 GitHub CLI运行 gh attestation verify gramps-web-mcp-osx-arm64.tar.gz --repo Scormave/gramps-web-mcp：如果该文件不是由此仓库的发布工作流构建的，命令就会失败。

与镜像一样，同一个二进制文件也可以通过 HTTP 为其他计算机提供服务；请参阅传输方式。若要从源代码检出目录运行服务，请参阅开发者指南中的 本地开发。

面向支持视觉的 Agent 的图像

支持视觉的 Agent 可以通过 read_media 读取可选媒体， 也可以通过二进制 MCP 资源读取，例如 gramps://media/{handle}/thumbnail/{size} 和 gramps://media/{handle}/file。 read_media 默认返回缩略图：由服务根据原图渲染的 JPEG 预览图（图像含透明度时为 PNG），最长边为 1568 像素，确保文档扫描件中的手写内容和小号印刷文字清晰可辨。传入 size （1–4096）可获取更小或更大的预览图；图像不会放大。预览图会从像素重新编码，因此不会发送 EXIF（包括 GPS）、XMP、IPTC 和 ICC 元数据。预览图可由 JPEG、PNG、GIF、WebP、BMP、TIFF、TGA、PBM 和 QOI 原图渲染；多页文件只使用第一页。PDF 和其他非图像媒体，以及 AVIF、HEIC/HEIF、JPEG XL 和 SVG 图像没有预览图。使用 mode: "file" 获取原始文件，并省略 size。 文件模式会根据 MIME 类型返回图像、音频或嵌入式二进制资源内容；对于 MCP 客户端无法显示的图像（如 TIFF），会以嵌入式二进制内容返回，并提示使用缩略图。端到端分析能否进行，取决于 MCP 客户端是否将类型化工具内容或二进制资源内容转发给具备相应能力的模型。

配置

Gramps 连接

变量	描述
GRAMPS_API_URL	Gramps Web 实例的基础 URL（末尾不带斜杠）
GRAMPS_USERNAME	API 用户名
GRAMPS_PASSWORD	API 密码
GRAMPS_TREE_ID	该服务上的树 UUID

使用刷新令牌代替密码

如果 Gramps Web 已关闭密码登录（OIDC_DISABLE_LOCAL_AUTH=true）， 请设置 GRAMPS_REFRESH_TOKEN，并取消设置 GRAMPS_USERNAME 和 GRAMPS_PASSWORD。 服务会通过 /api/token/refresh/ 将其换取访问令牌。

趁密码登录仍开启时获取一个：

curl -s -X POST https://gramps.example.com/api/token/ \
  -H 'Content-Type: application/json' \
  -d '{"username":"mcp","password":"..."}' | jq -r .refresh_token

Gramps Web 刷新令牌不会过期。请像保护密码一样保护它。删除用户或轮换 Gramps Web 密钥会使其失效。

运行模式

变量	默认值
GRAMPS_READ_ONLY	false
GRAMPS_MUTATION_SERIALIZE	true
GRAMPS_MUTATION_MIN_INTERVAL_MS	0

• GRAMPS_READ_ONLY：设为 true 可仅发布读取工具，并阻止直接的创建、更新和删除调用。
• GRAMPS_MUTATION_SERIALIZE：在此进程中，每次只运行一个创建/更新/删除 HTTP 调用。它还会保护更新工具完整的读取/修改/写入流程，避免受到此进程中其他此类调用的影响。
• GRAMPS_MUTATION_MIN_INTERVAL_MS：修改类 HTTP 调用之间的最短间隔。

运行说明：

• GRAMPS_READ_ONLY=false 表示服务以读写模式启动。
• Claude Desktop MCPB 扩展是例外：为了首次使用时更安全，其设置表单默认启用只读模式。
• 写入序列化和可选的间隔设置可保护常见的 Gramps Web SQLite 树，避免 Agent 突发写入。
• 写入门控仅在进程内生效。它不会协调多个 MCP 副本、Gramps Web UI 或其他 API 客户端之间的操作。
• 如果 SQLite 部署在顺序编辑时仍出现 database is locked，请设置 GRAMPS_MUTATION_MIN_INTERVAL_MS=250 或 500。
• 遇到 SQLite 锁定错误或上游 HTTP 429 时，修改工具会返回可重试的 MCP 错误，并附带简短的退避提示，而不是通用的 500 错误。
• 如果 Gramps Web 使用 PostgreSQL，且你希望并行写入，请设置 GRAMPS_MUTATION_SERIALIZE=false。

确认删除和撤销

当客户端支持 MCP elicitation 时，delete_object 和 undo_change 会在更改树之前，在对话框中请求用户确认。对话框会显示记录名称，或列出撤销操作将更改的内容，用户勾选复选框即可继续。拒绝或关闭对话框不会造成任何更改。试运行和拒绝操作不会请求确认。

变量	描述	默认值
GRAMPS_CONFIRMATION	when-supported 会向支持 elicitation 的客户端请求确认，在其他客户端中则照常运行；required 会拒绝无法请求确认的客户端中的删除和撤销操作；off 表示从不请求确认	when-supported

• 无状态 Streamable HTTP（默认情况下为 MCP_STATELESS=true）无法向客户端发送请求，因此不会请求确认，并且会在此模式下拒绝所有删除和撤销操作。设置 MCP_STATELESS=false 可通过 HTTP 请求确认；stdio 和旧版 SSE 会保留会话，因此可以请求确认。
• 无论设置如何，这两个工具都带有 anthropic/requiresUserInteraction 工具元数据。遵循该元数据的客户端（例如 Claude Code）会先请求自己的权限，因此用户可能需要确认两次；设置为 off 时，则只保留客户端的提示。
• 工具调用会一直等待，直到用户答复。如果客户端先取消调用，则不会造成任何更改。
• 服务会针对每个客户端记录一次是否请求确认。

有关对话框和回复，请参阅工具目录。

更新关联记录

九个接受关联列表的 update_* 工具都有一个 linkMode 参数：replace（默认值）、add 或 remove。例如，update_person(handle: "PERSON_HANDLE", noteHandles: ["NOTE_HANDLE"], linkMode: "add") 会添加一条备注，而不会复制此人的现有备注列表。remove 会接收要取消关联的句柄。未提供的列表保持不变；只有在 replace 模式下，[] 才会清空列表。该模式适用于此次调用中提供的所有关联列表。add 会保留现有关联元数据；若要更改这些元数据，请使用 replace。有关支持的列表和并发限制，请参阅工具目录。

2.3.1 之前的更新会丢失的数据

在 2.3.1 之前，update_* 工具可能会丢弃调用中未提及的已存储数据（#5）。如果你曾使用早期版本编辑过树，scripts/find-update-losses.py 会读取 Gramps Web 事务历史，并列出更新清空的所有值、这些值原先的内容，以及记录是否仍缺少这些值：

GRAMPS_API_URL=https://gramps.example.com GRAMPS_USERNAME=me GRAMPS_PASSWORD=... \
  python3 scripts/find-update-losses.py --user MCP_ACCOUNT --until 2026-10-07 --json losses.json

此脚本需要 Python 3.9 或更高版本，以及能够查看私有记录的账户；它只读取数据。历史记录中也包含在 Gramps Web 界面中进行的编辑，而且有意清除的值看起来与丢失的值相同，因此请在恢复前检查每项发现。

媒体文件访问

媒体字节工具/资源默认处于禁用状态。无需启用文件下载，get_object 配合 objectType: "media" 仍可用于获取元数据。 禁用时，read_media 不会出现在 tools/list 中；已知其名称的客户端直接调用时会收到配置错误，且不会下载字节数据。同一设置也会启用或禁用 上传。

变量	描述	默认值
GRAMPS_MEDIA_RESOURCES_ENABLED	启用用于缩略图和完整文件的二进制媒体工具/资源，以及上传功能	false
GRAMPS_MEDIA_MAX_BYTES	read_media 或任何媒体资源返回的最大字节数	5242880
GRAMPS_MEDIA_ALLOW_PRIVATE	允许读取标记为私有的 Gramps 媒体记录的字节数据	false

建议使用 read_media(mode: "thumbnail") 或 gramps://media/{handle}/thumbnail/{size} 进行 AI 分析。完整文件可能很大且包含敏感信息，也会保留其原始元数据， 并且仍受大小和私有记录检查的限制。

GRAMPS_MEDIA_MAX_BYTES 限制返回给客户端的内容。要生成 缩略图，服务会将原始文件从 Gramps Web 下载到内存中，最大为 50 MiB 或 GRAMPS_MEDIA_MAX_BYTES 中的较大值，并且最多支持 100 百万像素；返回的只有预览图。

GRAMPS_MEDIA_ALLOWED_MIME_TYPES 已不再使用。请从配置中 移除它；服务会忽略该变量，并在启动时记录警告（如果已设置）。

媒体上传

create_media 会从服务上的文件夹上传照片、文档扫描件或 PDF，并将其显示在 attachTo 指定的记录中；update_media 使用 filePath 替换记录的文件。上传需要启用媒体文件访问 （GRAMPS_MEDIA_RESOURCES_ENABLED=true），并且在 GRAMPS_MEDIA_UPLOAD_DIRS 中至少配置一个文件夹；在这两个条件都满足之前， create_media 都不会显示。只能读取这些文件夹内的文件（包括符号链接）， 并且只允许上传 JPEG、PNG、GIF、WebP、TIFF、BMP 和 PDF 文件，文件类型根据内容 判断。如果目录树中已存储该文件，则会复用，而不会重复上传。在 Docker 中，请将文件夹挂载到容器中，并设置为容器内可见的路径。

变量	描述	默认值
GRAMPS_MEDIA_UPLOAD_DIRS	create_media 和 update_media 可从中上传文件的绝对路径，以 : 分隔（Windows 上使用 ;）	未设置（关闭）
GRAMPS_MEDIA_UPLOAD_MAX_BYTES	create_media 或 update_media 上传的最大文件大小	52428800

传输方式

按上述说明设置 GRAMPS_API_URL、GRAMPS_TREE_ID，以及用户名/密码组合或 GRAMPS_REFRESH_TOKEN。

值	行为
（未设置或 stdio）	通过 stdin/stdout 使用 JSON-RPC（默认；本地客户端）。
http	在 MCP_PATH（默认值为 /mcp）提供 Streamable HTTP。
sse	旧版 MCP SSE：GET {MCP_PATH}/sse + POST {MCP_PATH}/message。有状态；仅供较旧的客户端使用。

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

可选（MCP 传输）

变量	描述	默认值
ASPNETCORE_URLS	HTTP/SSE 的监听 URL	—
MCP_PATH	MCP 端点的 URL 前缀	/mcp
MCP_STATELESS	Streamable HTTP 的无状态模式	true
MCP_ENABLE_LEGACY_SSE	使用 http 传输时公开旧版 /sse	false
MCP_API_KEY	HTTP/SSE 传输的共享密钥（轮换时以逗号分隔；至少 16 个字符）	—
MCP_ALLOWED_ORIGINS	允许调用 HTTP/SSE 端点的浏览器源，以逗号分隔；来自其他源的请求将收到 403	—

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 上发布端口，也会出现警告。如果外部访问已受到限制，这是预期行为。

浏览器来源

浏览器会在请求中发送 Origin 标头，服务器会对来源未列在 MCP_ALLOWED_ORIGINS 中的每个请求返回 403。这可以防止其他网站上的网页使用服务器的 Gramps 凭据调用工具，也能防止 DNS 重绑定攻击；即使服务器仅监听 127.0.0.1，此保护也有效。浏览器以外的 MCP 客户端（例如 Claude Desktop、Claude Code 和 SDK 客户端）不会发送 Origin，无需进行任何设置。对于你信任的基于浏览器的 MCP 客户端，请列出其来源：

MCP_ALLOWED_ORIGINS=https://app.example.com

SECURITY.md 还介绍了对 Host 标头进行的可选 AllowedHosts 检查。

日志记录

变量	说明	默认值
GRAMPS_LOG_LEVEL	服务器自身消息的日志级别：Trace、Debug、Information、Warning、Error、Critical、None	Information

日志会输出到 stderr。Claude Desktop 会将日志保存到本地文件（macOS 上的 ~/Library/Logs/Claude/mcp-server-Gramps Web MCP.log）。

在 Information 级别下，每次 Gramps API 调用都会记录其方法、路径（不含查询字符串）、状态、耗时和正文长度；媒体下载则记录内容类型和长度，而非正文长度。请求和响应正文以及完整 URL 中包含家谱数据（姓名、日期、搜索词），因此只有在 Debug 或 Trace 级别下才会记录。即使在这些级别下，看起来像凭据的字段也会被隐藏。仅在排查问题时使用 Debug，之后请删除日志文件。

开发

dotnet test

请参阅 CONTRIBUTING.md 和开发者指南。

文档

文档	说明
文档索引	所有文档文件
工具目录	完整的 MCP 工具参考
Claude Desktop MCPB	桌面扩展打包
隐私政策	桌面扩展的数据处理方式
系统提示词	提供给 MCP 客户端的建议提示词
架构	系统设计概述

贡献

欢迎贡献。请参阅 CONTRIBUTING.md。

安全

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

隐私政策

Claude Desktop 扩展是一个本地 MCP 服务。它只会向你配置的 Gramps Web 实例发送数据，不会收集分析数据或对话数据。完整详情请参阅 PRIVACY.md。

许可证

Copyright (c) Scormave

本项目采用 GNU Affero General Public License v3.0（AGPL-3.0-or-later）授权。由于这是网络服务端软件，托管修改后的版本时，必须向通过网络与其交互的用户提供相应的源代码。

捆绑的第三方组件（例如 ImageSharp、MCP C# SDK 和 .NET 运行时）各自保留 Apache 2.0 或 MIT 许可证；请参阅 THIRD-PARTY-NOTICES.txt。MCP Bundles 和 Docker 镜像会将该文件与 LICENSE 一并提供。