gramps-web-mcp

# gramps-web-mcp

[![License: AGPL v3](https://img.shields.io/badge/License-AGPL%20v3-blue.svg)](LICENSE)
[![.NET 10](https://img.shields.io/badge/.NET-10.0-512BD4)](https://dotnet.microsoft.com/download/dotnet/10.0)

Companion MCP server for the [Gramps Web](https://www.grampsweb.org/)
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](GrampsWeb.Mcp/docs/TOOL_CATALOG.md) for the full list.

All outgoing requests to Gramps Web, including authentication, media downloads,
and health checks, automatically identify this application with
`User-Agent: gramps-web-mcp/<version> (+https://github.com/Scormave/gramps-web-mcp)`.
The version comes from the application build; no configuration is required.

## Prerequisites

- [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0) (for local development)
- A running [Gramps Web](https://www.grampsweb.org/) 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](https://demo.grampsweb.org)
instance using well-known demo credentials (`owner` / `owner`):

```bash
./run-local-server.sh
```

The server starts with HTTP transport at `http://127.0.0.1:8080/mcp`. No API key is
required when binding to loopback only.

### 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:

```bash
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
```

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.

The image defaults to Streamable HTTP (`MCP_TRANSPORT=http`) on port 8080, which
is what the commands above use. Clients that spawn the container themselves
(such as MCP Registry installs) instead run it over stdio with
`-e MCP_TRANSPORT=stdio` and stdin kept open (`docker run -i`); that is the mode
declared in `server.json`.

For read-only mode, add `-e GRAMPS_READ_ONLY=true`:

```bash
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 installation

Unraid users can install `gramps-web-mcp` from **Community Applications**. The
template source is maintained at
[Scormave/gramps-web-mcp-unraid](https://github.com/Scormave/gramps-web-mcp-unraid).
For Unraid-specific help, see the
[support thread on the Unraid forums](https://forums.unraid.net/topic/199622-support-gramps-web-mcp-mcp-server-for-gramps-web-ai-genealogy).

Basic setup:

1. In Unraid, open **Apps** / **Community Applications**.
2. Search for `gramps-web-mcp` and install the template.
3. Set `GRAMPS_API_URL`, `GRAMPS_USERNAME`, `GRAMPS_PASSWORD`, and
   `GRAMPS_TREE_ID` for your Gramps Web instance. Set `MCP_API_KEY` when the
   MCP port is reachable from other machines on your network.
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`](docker-compose.example.yml) as a starting point:

```bash
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](https://github.com/Scormave/gramps-web-mcp/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` |
| Linux x64 | `gramps-web-mcp-claude-desktop-linux-x64-v*.mcpb` |
| Linux ARM64 | `gramps-web-mcp-claude-desktop-linux-arm64-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`](mcpb/README.md) for packaging details and
[`PRIVACY.md`](PRIVACY.md) for the privacy policy.

To build a bundle locally:

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

### MCP client configuration (manual)

**stdio** (e.g. Claude Desktop, Cursor):

```json
{
  "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.
When `MCP_API_KEY` is set, send it as `Authorization: Bearer <key>` or
`X-Api-Key: <key>` on every MCP request.

```bash
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}'
```

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 | Default |
|----------|---------|
| `GRAMPS_READ_ONLY` | `false` |
| `GRAMPS_MUTATION_SERIALIZE` | `true` |
| `GRAMPS_MUTATION_MIN_INTERVAL_MS` | `0` |

- `GRAMPS_READ_ONLY`: set to `true` to block create, update, and delete calls
  while keeping tools visible.
- `GRAMPS_MUTATION_SERIALIZE`: runs create/update/delete HTTP calls one at a
  time in this process.
- `GRAMPS_MUTATION_MIN_INTERVAL_MS`: minimum pause between mutation HTTP calls,
  including steps inside composite tools.

Runtime notes:

- `GRAMPS_READ_ONLY=false` means the server starts in read/write mode.
- The Claude Desktop MCPB extension is the exception: its setup form defaults to
  read-only for safer first use.
- Write serialization and the optional interval protect typical Gramps