Gramps Web MCP — Claude Code MCP server: features & install
Connects AI assistants to your Gramps Web family tree via the Model Context Protocol. Helps you trace lineages and search genealogy records directly from chat.
claude mcp add --env MCP_TRANSPORT=<MCP_TRANSPORT> --env GRAMPS_API_URL=<GRAMPS_API_URL> --env GRAMPS_USERNAME=<GRAMPS_USERNAME> --env GRAMPS_PASSWORD=<GRAMPS_PASSWORD> --env GRAMPS_REFRESH_TOKEN=<GRAMPS_REFRESH_TOKEN> --transport stdio gramps-web-mcp -- docker run -i --rm -e MCP_TRANSPORT -e GRAMPS_API_URL -e GRAMPS_USERNAME -e GRAMPS_PASSWORD -e GRAMPS_REFRESH_TOKEN ghcr.io/scormave/gramps-web-mcp:2.6.0What Gramps Web MCP does
Gramps Web MCP acts as an intermediary bridge between your LLM assistant and an active Gramps Web installation. It does not replace the genealogy user interface. The server equips models with up to 32 operations, covering record management for individuals, families, and citations.
Built-in navigation capabilities include kinship mapping for family lines and filtering via Gramps QL. Sensitive actions like removing records or rolling back transactions trigger direct confirmation dialogs if the client environment supports MCP elicitation. Image previews automatically strip EXIF coordinates to safeguard private location details.
Local deployment requires Docker and a reachable Gramps Web API target. Running the container without pre-configured login credentials or an active genealogy instance results in connection failure.
What it helps with
- trace direct ancestor or descendant lines for a family member
- append citations and notes to an existing birth event
- filter records for unlinked individuals or specific kinship groups
- revert past edits without breaking subsequent data links
Example prompts for the agent
- Show me all direct ancestors of person
I0001up to four generations. - Attach a new census citation to the marriage record in family
F0012. - Find every individual in the tree matching the surname Miller.
How to install Gramps Web MCP
Platform CLI
claude mcp add --env MCP_TRANSPORT=<MCP_TRANSPORT> --env GRAMPS_API_URL=<GRAMPS_API_URL> --env GRAMPS_USERNAME=<GRAMPS_USERNAME> --env GRAMPS_PASSWORD=<GRAMPS_PASSWORD> --env GRAMPS_REFRESH_TOKEN=<GRAMPS_REFRESH_TOKEN> --transport stdio gramps-web-mcp -- docker run -i --rm -e MCP_TRANSPORT -e GRAMPS_API_URL -e GRAMPS_USERNAME -e GRAMPS_PASSWORD -e GRAMPS_REFRESH_TOKEN ghcr.io/scormave/gramps-web-mcp:2.6.0Replace <…> with your own values. 10 more environment variables are in the server README
Platform CLI
codex mcp add gramps-web-mcp --env MCP_TRANSPORT=<MCP_TRANSPORT> --env GRAMPS_API_URL=<GRAMPS_API_URL> --env GRAMPS_USERNAME=<GRAMPS_USERNAME> --env GRAMPS_PASSWORD=<GRAMPS_PASSWORD> --env GRAMPS_REFRESH_TOKEN=<GRAMPS_REFRESH_TOKEN> -- docker run -i --rm -e MCP_TRANSPORT -e GRAMPS_API_URL -e GRAMPS_USERNAME -e GRAMPS_PASSWORD -e GRAMPS_REFRESH_TOKEN ghcr.io/scormave/gramps-web-mcp:2.6.0Replace <…> with your own values. 10 more environment variables are in the server README
Config file
{
"mcpServers": {
"gramps-web-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"MCP_TRANSPORT",
"-e",
"GRAMPS_API_URL",
"-e",
"GRAMPS_USERNAME",
"-e",
"GRAMPS_PASSWORD",
"-e",
"GRAMPS_REFRESH_TOKEN",
"ghcr.io/scormave/gramps-web-mcp:2.6.0"
],
"env": {
"MCP_TRANSPORT": "<MCP_TRANSPORT>",
"GRAMPS_API_URL": "<GRAMPS_API_URL>",
"GRAMPS_USERNAME": "<GRAMPS_USERNAME>",
"GRAMPS_PASSWORD": "<GRAMPS_PASSWORD>",
"GRAMPS_REFRESH_TOKEN": "<GRAMPS_REFRESH_TOKEN>"
}
}
}
}Replace <…> with your own values. 10 more environment variables are in the server README
Config file
{
"servers": {
"gramps-web-mcp": {
"type": "stdio",
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"MCP_TRANSPORT",
"-e",
"GRAMPS_API_URL",
"-e",
"GRAMPS_USERNAME",
"-e",
"GRAMPS_PASSWORD",
"-e",
"GRAMPS_REFRESH_TOKEN",
"ghcr.io/scormave/gramps-web-mcp:2.6.0"
],
"env": {
"MCP_TRANSPORT": "<MCP_TRANSPORT>",
"GRAMPS_API_URL": "<GRAMPS_API_URL>",
"GRAMPS_USERNAME": "<GRAMPS_USERNAME>",
"GRAMPS_PASSWORD": "<GRAMPS_PASSWORD>",
"GRAMPS_REFRESH_TOKEN": "<GRAMPS_REFRESH_TOKEN>"
}
}
}
}Replace <…> with your own values. 10 more environment variables are in the server README
Platform CLI
gemini mcp add -e MCP_TRANSPORT=<MCP_TRANSPORT> -e GRAMPS_API_URL=<GRAMPS_API_URL> -e GRAMPS_USERNAME=<GRAMPS_USERNAME> -e GRAMPS_PASSWORD=<GRAMPS_PASSWORD> -e GRAMPS_REFRESH_TOKEN=<GRAMPS_REFRESH_TOKEN> gramps-web-mcp docker run -i --rm -e MCP_TRANSPORT -e GRAMPS_API_URL -e GRAMPS_USERNAME -e GRAMPS_PASSWORD -e GRAMPS_REFRESH_TOKEN ghcr.io/scormave/gramps-web-mcp:2.6.0Replace <…> with your own values. 10 more environment variables are in the server README
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Gramps Web MCP
How to install Gramps Web MCP in Claude Code?
Run the configuration command in your terminal: `claude mcp add --env MCP_TRANSPORT=<MCP_TRANSPORT> --env GRAMPS_API_URL=<GRAMPS_API_URL> --env GRAMPS_USERNAME=<GRAMPS_USERNAME> --env GRAMPS_PASSWORD=<GRAMPS_PASSWORD> --env GRAMPS_REFRESH_TOKEN=<GRAMPS_REFRESH_TOKEN> --transport stdio gramps-web-mcp -- docker run -i --rm -e MCP_TRANSPORT -e GRAMPS_API_URL -e GRAMPS_USERNAME -e GRAMPS_PASSWORD -e GRAMPS_REFRESH_TOKEN ghcr.io/scormave/gramps-web-mcp:2.6.0`.
What does Gramps Web MCP do?
It provides AI models with structured access to genealogical records stored in Gramps Web. Agents can query kinship paths, run text lookups, and make incremental updates to your tree.
Can the server run in read-only mode to protect family records?
Yes, setting -e GRAMPS_READ_ONLY=true in the container environment restricts the server to read operations and suppresses all update or delete tools.
