Skip to content

Quickstart

Jump to bottom
Alexey edited this page Jul 3, 2026 · 3 revisions

Quickstart: AI-powered genealogy research with Claude Code

This tutorial walks you through a complete local setup — Gramps Web, the MCP server, and Claude Desktop — and shows a real example session where Claude researches Marie Curie's family from Wikipedia and adds it directly to your database.

What you need:

Part 1 — Start Gramps Web

Create a new folder and add a docker-compose.yml (based on the official Gramps Web example):

services:
  grampsweb: &grampsweb
    image: ghcr.io/gramps-project/grampsweb:latest
    restart: unless-stopped
    ports:
      - "5000:5000"
    environment:
      GRAMPSWEB_TREE: main
      GRAMPSWEB_CELERY_CONFIG__broker_url: redis://grampsweb_redis:6379/0
      GRAMPSWEB_CELERY_CONFIG__result_backend: redis://grampsweb_redis:6379/0
      GRAMPSWEB_RATELIMIT_STORAGE_URI: redis://grampsweb_redis:6379/1
      GRAMPSWEB_GUNICORN_WORKERS: "1"
    volumes:
      - gramps_users:/app/users
      - gramps_index:/app/indexdir
      - gramps_thumb_cache:/app/thumbnail_cache
      - gramps_cache:/app/cache
      - gramps_secret:/app/secret
      - gramps_db:/root/.gramps
      - gramps_media:/app/media
      - gramps_tmp:/tmp
    depends_on:
      - grampsweb_redis
    healthcheck:
      test:
        [
          "CMD",
          "python3",
          "-c",
          "import urllib.request; urllib.request.urlopen('http://localhost:5000/')",
        ]
      interval: 5s
      timeout: 5s
      retries: 20
      start_period: 15s

  grampsweb_celery:
    <<: *grampsweb
    ports: []
    restart: unless-stopped
    depends_on:
      - grampsweb_redis
    healthcheck:
      disable: true
    command: celery -A gramps_webapi.celery worker --loglevel=INFO --concurrency=1

  grampsweb_redis:
    image: docker.io/valkey/valkey:8-alpine
    restart: unless-stopped

  grampsweb_init:
    # Creates the initial user account on first run.
    # || true makes the command idempotent — safe to run on every restart.
    image: ghcr.io/gramps-project/grampsweb:latest
    restart: "no"
    environment:
      GRAMPSWEB_TREE: main
    volumes:
      - gramps_users:/app/users
      - gramps_secret:/app/secret
    command: >
      sh -c "python3 -m gramps_webapi user add gramps-mcp gramps-mcp --email gramps-mcp@localhost --role 5 || true"
    depends_on:
      grampsweb:
        condition: service_healthy

  gramps_web_mcp:
    image: ghcr.io/alexey-n-chernyshov/gramps-web-mcp-rs:latest
    restart: unless-stopped
    environment:
      GRAMPS_API_URL: http://grampsweb:5000
      GRAMPS_USERNAME: gramps-mcp
      GRAMPS_PASSWORD: gramps-mcp
      GRAMPS_READONLY: false
      MCP_TRANSPORT: http
      MCP_HTTP_PORT: 3000
    ports:
      - "3000:3000"
    depends_on:
      grampsweb:
        condition: service_healthy

volumes:
  gramps_users:
  gramps_index:
  gramps_thumb_cache:
  gramps_cache:
  gramps_secret:
  gramps_db:
  gramps_media:
  gramps_tmp:

Start everything:

docker compose up -d

The grampsweb_init service waits for Gramps Web to be ready, then creates the admin account. On subsequent restarts || true makes it exit cleanly if the account already exists.

Open http://localhost:5000 and log in with gramps-mcp / gramps-mcp. You'll see an empty family tree — that's expected.

Part 2 — Connect Claude Code

In your working directory, run:

claude mcp add --transport http --scope project gramps-web http://localhost:3000/mcp

This creates a .mcp.json file in the current directory. Then start Claude Code:

claude

On first launch Claude Code will prompt you to approve the gramps-web MCP server — press y to allow it. You can verify the connection with:

/mcp

Part 3 — Research and enrich with Claude

Start a new conversation in Claude Code. The more context you give Claude, the better the result — you can describe the full task in one go:

Create a person record for Marie Curie in my Gramps database. Look her up on Wikipedia and fill in her birth date, birth place, death date, and death place. Add a short biographical note. Then find her husband and children on Wikipedia, create records for each of them with their dates and places, and link them to Marie as a family. Finally, find a public-domain portrait for each person on Wikimedia Commons and attach it to their record as the primary photo. Before attaching each photo, verify that the URL points directly to the image file, not to a page about the file.

You'll see each tool call appear in the Claude Code interface as it happens. Filling in the full family tree — dates, places, and portraits — takes around 10 minutes.

Note: LLMs can make mistakes — dates, places, or links may occasionally be wrong or hallucinated. Always review the result in Gramps Web before treating it as final. Claude will summarize what it did at the end, which makes it easy to spot anything that looks off.

Tip: project instructions

For repeated research sessions, create a dedicated folder and set it up once:

claude mcp add --transport http --scope project gramps-web http://localhost:3000/mcp

You can also add a CLAUDE.md to guide Claude's behavior across all sessions in that folder. For example, to tell Claude to always confirm before writing:

Before creating or updating any record in Gramps, summarize what you're about to do and wait for my approval.
Prefer Wikipedia as the primary source. Note any conflicting information you find.
Before attaching each photo, verify that the URL points directly to the image file, not to a page about the file.

Part 4 — Verify the result in Gramps Web

Open http://localhost:5000, go to People, and find Marie Curie.

You should see:

  • Full birth and death dates with places
  • Biographical note
  • Portrait photo
  • Family section showing Irène and Ève as children

Click on Irène or Ève to see their individual records.

Part 5 — Cleanup

Stop the services (data is preserved in Docker volumes):

docker compose down

Start again any time with docker compose up -d — your family tree will still be there.

Remove everything including data:

docker compose down -v

Clone this wiki locally