gramps-web-mcp

Companion MCP server for the Gramps Web open-source genealogy platform. It gives AI agents structured, tool-based access to family trees through the Model Context Protocol.

This project is not a standalone genealogy UI or replacement for Gramps Web. Run it alongside an existing Gramps Web instance; your users, trees, media, permissions, and genealogy editing UI stay in Gramps Web.

Features

• 57 MCP tools — read, create, update, and delete people, families, events, places, sources, citations, notes, media, repositories, and tags
• Search and browse — full-text search and paginated object listing
• Kinship tools — ancestors, descendants, relationships, and timelines
• Composite workflows — quick-add person, add event to person, find by Gramps ID
• 6 MCP resources — type vocabularies, input guide, tree metadata, name settings, and opt-in media thumbnails/files for vision-capable agents
• Media safeguards — size limits, MIME allowlists, and private-record defaults
• MCP prompts — guided workflows for research, adding people/families, and imports
• Multiple transports — stdio (local clients), Streamable HTTP, legacy SSE
• Read-only mode — keep all tools visible while blocking create, update, and delete calls

See the tool catalog for the full list.

Prerequisites

• .NET 8 SDK (for local development)
• A running Gramps Web instance with API access
• Docker (optional, for container deployment)

Quick start

Local development (demo server)

run-local-server.sh connects to the public demo.grampsweb.org instance using well-known demo credentials (owner / owner):

./run-local-server.sh

The server starts with HTTP transport at http://127.0.0.1:8080/mcp.

Docker

Pre-built multi-arch images (linux/amd64, linux/arm64) are published to GitHub Container Registry. Docker picks the matching architecture automatically; amd64 covers most Unraid and x86 hosts, arm64 covers Apple Silicon and ARM SBCs:

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 \
  ghcr.io/scormave/gramps-web-mcp:latest

The image exposes a GET /health endpoint for Docker HEALTHCHECK, Unraid container health, and other uptime monitors. It returns HTTP 200 when the MCP server can authenticate against Gramps Web, or HTTP 503 otherwise. The public response is minimal by default: { "status": "healthy" } or { "status": "unhealthy" }. Startup logs include a line such as Connected to Gramps Web at … once the API is reachable.

For read-only mode, add -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 GRAMPS_READ_ONLY=true \
  ghcr.io/scormave/gramps-web-mcp:latest

Unraid installation

Unraid users can install gramps-web-mcp from Community Applications. The template source is maintained at Scormave/gramps-web-mcp-unraid. For Unraid-specific help, see the support thread on the Unraid forums.

Basic setup:

1. In Unraid, open Apps / Community Applications.
2. Search for gramps-web-mcp and install the template.
3. Set the Gramps Web connection values: GRAMPS_API_URL, GRAMPS_USERNAME, GRAMPS_PASSWORD, and GRAMPS_TREE_ID.
4. Keep the default container port 8080, or map it to another host port.
5. Start the container and check /health; it returns HTTP 200 once the service can authenticate to Gramps Web, with a minimal JSON response by default.

For the easiest pairing, run Gramps Web and gramps-web-mcp on the same Unraid Docker network and set GRAMPS_API_URL to the Gramps Web container URL. The MCP endpoint for clients is http://<unraid-host>:<mapped-port>/mcp.

Gramps Web + MCP (Docker Compose)

To run Gramps Web and the MCP server on the same host and Docker network, use docker-compose.example.yml as a starting point:

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 is published on port 5055; MCP is on 8080 (/mcp and /health). Inside the compose network the MCP container reaches Gramps Web at http://grampsweb:5000.

Claude Desktop (MCPB extension)

One-click install for Claude Desktop is available as an MCP Bundle (.mcpb) from GitHub Releases. Download the bundle for your platform:

Platform	Artifact
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

1. Download the .mcpb file for your OS from the latest release.
2. Double-click it, or drag it into the Claude Desktop window.
3. Enter your Gramps Web URL, username, password/token, and tree UUID.
4. Leave Read-only mode enabled for your first session; disable it only when you want Claude to create or edit records.
5. Complete installation and start a new chat.

The extension runs locally over stdio and does not require the .NET SDK on your machine. See mcpb/README.md for packaging details and PRIVACY.md for the privacy policy.

To build a bundle locally:

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

MCP client configuration (manual)

stdio (e.g. 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"
      }
    }
  }
}

To run a stdio server in read-only mode, add "GRAMPS_READ_ONLY": "true" to env.

HTTP (remote / Docker):

Point your MCP client at http://host:8080/mcp with Streamable HTTP transport.

Vision-capable agents can read opt-in media through tools (GetMediaThumbnail, GetMediaFile) or through binary MCP resources such as gramps://media/{handle}/thumbnail/{size} and gramps://media/{handle}/file. GetMediaFile returns image, audio, or embedded blob resource content depending on MIME type. End-to-end analysis depends on the MCP client forwarding the typed tool content or binary resource content to a capable model.

Configuration

Required (Gramps connection)

Variable	Description
GRAMPS_API_URL	Base URL of your Gramps Web instance (no trailing slash)
GRAMPS_USERNAME	API user name
GRAMPS_PASSWORD	API password or token
GRAMPS_TREE_ID	Tree UUID on that server

Runtime mode

Variable	Behavior	Default
GRAMPS_READ_ONLY=true	Blocks create, update, and delete mutation calls while keeping tools visible	read/write

Media file access

Media byte tools/resources are disabled by default. get_media remains available for metadata without enabling file downloads.

Variable	Description	Default
GRAMPS_MEDIA_RESOURCES_ENABLED	Enables binary media tools/resources for thumbnails and full files	false
GRAMPS_MEDIA_MAX_BYTES	Maximum bytes returned by any media resource	5242880
GRAMPS_MEDIA_ALLOWED_MIME_TYPES	Comma-separated allowlist; exact types and type/* wildcards are supported	image/jpeg,image/png,image/webp,image/avif,application/pdf
GRAMPS_MEDIA_ALLOW_PRIVATE	Allows bytes for Gramps media records marked private	false

Prefer GetMediaThumbnail or gramps://media/{handle}/thumbnail/{size} for AI analysis. Full files can be large and sensitive, and are still subject to the same size, MIME, and private-record checks.

Transports

Set GRAMPS_API_URL, GRAMPS_USERNAME, GRAMPS_PASSWORD, and GRAMPS_TREE_ID as usual.

MCP_TRANSPORT	Behavior
(unset or stdio)	JSON-RPC over stdin/stdout (default; local clients).
http	Streamable HTTP at MCP_PATH (default /mcp). Responses stream over SSE. Set ASPNETCORE_URLS (e.g. http://127.0.0.1:8080).
sse	Legacy MCP SSE: GET {MCP_PATH}/sse + POST {MCP_PATH}/message. Stateful; use for older clients only.

Optional (MCP transport)

Variable	Description	Default
ASPNETCORE_URLS	Listen URLs for HTTP/SSE	—
MCP_PATH	URL prefix for MCP endpoints	/mcp
MCP_STATELESS	Stateless mode for Streamable HTTP	true
MCP_ENABLE_LEGACY_SSE	Expose legacy /sse with http transport	false

Development

dotnet test

See CONTRIBUTING.md and the developer guide.

Documentation

Document	Description
docs index	All documentation files
Tool catalog	Complete MCP tool reference
Claude Desktop MCPB	Desktop extension packaging
Privacy policy	Data handling for the desktop extension
System prompt	Suggested prompt for MCP clients
Architecture	System design overview

Contributing

Contributions are welcome. See CONTRIBUTING.md.

Security

To report a vulnerability, see SECURITY.md.

Privacy Policy

The Claude Desktop extension is a local MCP server. It sends data only to the Gramps Web instance you configure and does not collect analytics or conversation data. See PRIVACY.md for full details.

License

Copyright (c) Scormave

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0-or-later). Because this is network server software, hosting a modified version requires making the corresponding source available to users interacting with it over a network.