gramps-web-mcp

![License: AGPL v3](LICENSE) ![.NET 8](https://dotnet.microsoft.com/download/dotnet/8.0)

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:

In Unraid, open Apps / Community Applications.
Search for gramps-web-mcp and install the template.
Set the Gramps Web connection values:

GRAMPS_API_URL, GRAMPS_USERNAME, GRAMPS_PASSWORD, and GRAMPS_TREE_ID.

Keep the default container port 8080, or map it to another host port.
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 |

Download the .mcpb file for your OS from the latest release.
Double-click it, or drag it into the Claude Desktop window.
Enter your Gramps Web URL, username, password/token, and tree UUID.
Leave Read-only mode enabled for your first session; disable it only when you

want Claude to create or edit records.

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

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.

Gramps Web MCP