geni-mcp

An MCP server for the Geni.com genealogy API. It covers all 89 documented REST endpoints with 48 tools, and is built for careful research on a shared world tree. Requests are slow on purpose, every write is logged, and anything that changes the tree's structure must be enabled explicitly.

What it does

• Read the tree:

  • profiles, singly or 50 at a time;

  • immediate family;

  • ancestors up to 20 generations in one call, numbered Ahnentafel-style, with a list of missing numbers;

  • descendants, found by walking the tree;

  • relationship paths (with Geni's notifications and emails turned off);

  • side-by-side comparison of two profiles;

  • name search and tree matches.

• Edit profiles:

  • change names, events, occupation and visibility, with a dry-run preview showing before and after;

  • append dated research notes to a profile's About text without touching what's already there.

• Add sources: create documents from scans, PDFs, transcriptions or URLs, tag them to profiles, and comment on them.

• Work with media and the rest:

  • photos, videos and albums, including main profile photos;

  • projects, surname pages, and your own lists (managed profiles, max family, followed items, uploads);

  • revisions and statistics;

  • a read-only geni_raw_get for anything else.

Related MCP server: gedcom-mcp

Safety model

• Structural tools also refuse to run without confirm: true on each call.

• Every write is appended to ~/.config/geni-mcp/audit.jsonl with a timestamp, the target, the request, and the earlier values where they were fetched. Uploaded file contents are never logged.

• Uploads of a local file need confirm: true; without it the tool names the file and its size and sends nothing. Files come only from the upload folders (GENI_UPLOAD_DIRS, default ~/Documents). Only known image, PDF, text and video types are accepted. Hidden files and the server's config folder are always refused, so text on a Geni profile can't trick Claude into publishing your private files.

• Pacing:

  • Requests are serialised and spaced 2 s apart by default; Geni allows 40 per 10 s.

  • The server honours Geni's X-API-Rate-* headers, and pauses the whole queue when throttled.

  • Every request times out after 60 s.

• Blocks: if Geni returns an IP-block page, the server refuses all further calls for 30 minutes.

• geni_raw_get refuses write endpoints (add, update, delete, merge, tag and similar), and any path containing %, ;, whitespace or control characters, which could hide one.

Setup

1. Register an app at https://www.geni.com/platform/developer/apps with callback http://localhost:3000/oauth/callback.

2. Install and build:

   git clone https://github.com/j-s-au/geni-mcp.git ~/geni-mcp
   cd ~/geni-mcp && npm ci && npm run build

3. Configure it: cp env.example ~/.config/geni-mcp/env && chmod 600 ~/.config/geni-mcp/env, then fill in the app id and secret.

4. Register the server with Claude Code: claude mcp add geni -s user -- ~/geni-mcp/run-local.sh

5. In Claude, run auth_start and open the URL. A local listener on port 3000 catches Geni's redirect and saves the token to ~/.config/geni-mcp/tokens.json (mode 600). The token refreshes automatically.

   • If the listener can't start, paste the redirect URL into auth_complete instead.

Tools

Endpoints deliberately left out: user/add, which creates Geni accounts.

Things the Geni docs leave open

These assumptions are based on the docs and should be confirmed on first live use. See the Geni developer docs at https://www.geni.com/platform/developer/help.

• The REST error format and the HTTP status for throttling are undocumented. Errors are classified defensively.

• The {focus, nodes} structure returned by ancestors and immediate-family is undocumented. The parser reads edges with rel: partner | child from both sides.

• Dates on document, photo and video writes are sent as a JSON-serialised Date object, as the docs describe.

• The batch ids= response shape is assumed to be {results: [...]}. Anything else is returned as-is.

• merge_profiles does not document which profile survives.

• append_about_note must replace the whole About text, because Geni has no append. It re-reads the text just before writing and refuses if it changed, or if About text exists only in another language.

• profile/search documents only a names parameter.

Development

npm test            # unit + tool tests with a fake Geni (no network)
npm run coverage    # 80% thresholds enforced
npm run typecheck
npm run build