geni-mcp
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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_getfor anything else.
Related MCP server: gedcom-mcp
Safety model
| Allows |
| Reads only |
| Plus in-place edits: profile and union updates, notes, documents, media, tags, comments, projects, follows |
| Plus structural changes: |
Structural tools also refuse to run without
confirm: trueon each call.Every write is appended to
~/.config/geni-mcp/audit.jsonlwith 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 at least 2 s apart, or
X-API-Rate-Window / X-API-Rate-Limitif that is longer (Geni says limits change without notice, so the headers decide).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_getrefuses write endpoints (add, update, delete, merge, tag and similar), and any path containing%,;, whitespace or control characters, which could hide one.
Setup
Register an app at https://www.geni.com/platform/developer/apps with callback
http://geni-mcp.test:3000/oauth/callback.Geni's firewall blocks redirect URIs containing
localhost(and can block your IP for 24 hours), so use a made-up hostname and map it to this computer:echo "127.0.0.1 geni-mcp.test" | sudo tee -a /etc/hosts.
Install and build:
git clone https://github.com/j-s-au/geni-mcp.git ~/geni-mcp cd ~/geni-mcp && npm ci && npm run buildConfigure it:
cp env.example ~/.config/geni-mcp/env && chmod 600 ~/.config/geni-mcp/env, then fill in the app id and secret.Register the server with Claude Code:
claude mcp add geni -s user -- ~/geni-mcp/run-local.shIn Claude, run
auth_startand open the URL. A listener on 127.0.0.1, 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, or there is no hosts entry (the browser then shows an error page), paste the redirect URL into
auth_completeinstead.
Tools
Tool | Level | Purpose |
| read | Log in to Geni |
| read | Finish Geni login manually |
| read | Login state, token expiry, rate-limit headers, write level |
| read | Revoke and delete the token |
| read | Current Geni user |
| read | Get a Geni profile |
| read | Get up to 50 profiles |
| read | Parents, siblings, partners, children, union ids |
| read | Ancestors (Ahnentafel), up to 20 generations (6 when walking, see below) |
| read | Descendants (one request per person) |
| read | Relationship and linking chain (no notifications) |
| read | Immediate families of two profiles side by side |
| read | Name search |
| read | Documents, photos or videos on a profile |
| read | Tree matches (experimental, undocumented endpoint) |
| safe | Update a profile |
| safe | Append a dated research note to About |
| safe | Follow or unfollow a profile |
| full + confirm | Create an unconnected profile |
| full + confirm | Add a parent, child, partner or sibling |
| full + confirm | Merge two profiles |
| full + confirm | Delete a profile |
| read | Get unions (couples) |
| safe | Update marriage or divorce |
| full + confirm | Add a child or partner to a couple |
| read | Get documents, photos, videos or albums |
| read | Comments, tagged profiles, projects or album photos |
| safe (+ confirm for a file) | Create a document (source) |
| safe + confirm | Upload a photo or video |
| safe (+ confirm for a file) | Set a profile's main photo |
| safe | Update a document, photo or video |
| safe | Tag or untag profiles |
| safe | Comment on a document, photo or video |
| full + confirm | Delete a document, photo or video |
| safe | Create or rename a photo album |
| read | Get projects |
| read | Search projects |
| read | Project profiles, collaborators or followers |
| safe | Add profiles or documents to a project |
| safe | Update a project |
| read | Get a surname page |
| read | Surname profiles or followers |
| read | Managed profiles, max family, followed items, uploads, albums, labels |
| read | Read this app's per-user note (512 bytes) |
| safe | Save this app's per-user note |
| read | Get a revision |
| read | World Family Tree size and statistics |
| read | Raw GET for any API path |
Endpoints deliberately left out: user/add, which creates Geni accounts.
Things the Geni docs leave open
Confirmed live on 28 Oct 2026:
immediate-familyreturns{focus, nodes}, with profiles and unions linked byedges(rel: partner | child) on both sides. Nodes are keyed by numeric id even when you ask by GUID.Batch
ids=returns{results: [...]}, not in request order.Errors look like
{error: {type, message}}, e.g. 403ApiException: Approved client app required.ApiException: Permission denied(403) is the other refusal wording seen forprofile/ancestors; any plain 403 there triggers the walk.In practice this app's user token gets
X-API-Rate-Limit: 1,X-API-Rate-Window: 10(1 request per 10 s, not the documented 40), so expect about 10 s per call. 429 body:ApiException: Rate limit exceeded.platform/oauth/validate_tokenneeds?access_token=; with only a Bearer header it answers 400invalid_token.profile/ancestorsneeds an app approved by Geni. Until thenget_ancestorsclimbsimmediate-familyone person per request, capped at 6 generations.Geni's firewall blocks a
localhostredirect URI (see Setup).
Still assumptions, to be confirmed on first use: See the Geni developer docs at https://www.geni.com/platform/developer/help.
The HTTP status for throttling is undocumented. Errors are classified defensively.
Dates on document, photo and video writes are sent as a JSON-serialised Date object, as the docs describe.
merge_profilesdoes not document which profile survives.append_about_notemust 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/searchdocuments only anamesparameter.
Development
npm test # unit + tool tests with a fake Geni (no network)
npm run coverage # 80% thresholds enforced
npm run typecheck
npm run buildTool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
MCP server for Gramps genealogy via the Gramps Web API: CRUD, search, merge, timelines, DNA.
Read-only A2Me family context tools for AI assistants (members, dates, activity, relationships)
Search and read public data from X/Twitter, Reddit, YouTube, Instagram, TikTok, Facebook, Threads, Bluesky, Trustpilot, Amazon, Google Maps, news, forums and the web. 90+ read-only tools plus ready-made research playbooks (lead finding, brand monitoring, review mining). Hosted: connect with an API key; 50 free requests per endpoint each month.
Family history and genealogy in your AI: your tree and FamilySearch, with a source for every fact.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to create, edit, and query genealogical data from GEDCOM files. Supports complex genealogy searches, automatic data enrichment from web sources, relationship analysis, and biography generation for individuals and families.17MIT
- AlicenseAqualityCmaintenanceEnables users to read, search and edit GEDCOM (.ged) family-tree files from Ancestry.com and other genealogy software, letting an MCP client navigate relationships, explore ancestor and descendant trees, inspect sources and citations, and make safe, lossless edits that are written straight back to the file with a backup.192MIT
- AlicenseAqualityBmaintenanceEnables direct interaction with FamilySearch.org's shared Family Tree and historical records, including reading and adding people, facts, relationships, sources, notes, memories, record search, and image downloads, without needing a browser.39MIT
- AlicenseAqualityBmaintenanceEnables AI assistants to read and write a self-hosted Gramps Web family tree through the REST API, creating facts with citations attached and auditing unsourced or duplicate data with 83 evidence-disciplined tools. It also exposes legacy GEDCOM exports as a read-only reference layer of untrusted hints, with living-person privacy filtering on by default.9766 PyPIMIT