# ancestry-com-mcp

An MCP server that lets an AI assistant do everything you would do on Ancestry.com by hand: search records,
read and edit your trees (people, facts, sources, citations, notes, tags, media), review hints, attach records,
look at DNA matches, and read or send messages.

Ancestry has no public API. This server drives the site's own internal JSON endpoints, reverse-engineered
and documented in [`docs/endpoints.md`](docs/endpoints.md) and [`docs/writes.md`](docs/writes.md).

Companion server: [familysearch-org-mcp](https://github.com/ball2jh/familysearch-org-mcp). Both can be attached at once.

> **Unofficial.** This project is not affiliated with or endorsed by Ancestry. It uses undocumented endpoints
> that may change or break at any time, and automated access may be against Ancestry's terms of service.
> Use it only with your own account, on your own trees, at your own risk.

## How it works

Cloudflare rejects ordinary Node/curl TLS on ancestry.com even with valid cookies, but it accepts a client that
impersonates Chrome's TLS/HTTP2 fingerprint ([impit](https://github.com/apify/impit)) carrying the site's two
login cookies (`ATT`, `SecureATT`). So the server runs **without a browser**: cookies live in `.session.json`
(mode 600, git-ignored) and every request goes straight from Node. A real Chrome is opened only to sign in:
`pnpm login` (or the `ancestry_session login` tool action) launches a dedicated Chrome profile on the sign-in
page, waits for you to log in, saves the cookies, and closes the window again.

Requirements: Node 26+ (runs TypeScript directly), pnpm, Google Chrome.

## Setup

```bash
git clone https://github.com/ball2jh/ancestry-com-mcp
cd ancestry-com-mcp
pnpm install
pnpm login            # one-time: opens Chrome to sign in, saves .session.json, closes Chrome
pnpm smoke            # optional: read-only check of the connection and client
```

Add to Claude Code / Claude Desktop (stdio):

```json
{
  "mcpServers": {
    "ancestry": {
      "command": "node",
      "args": ["/absolute/path/to/ancestry-com-mcp/src/server.ts"]
    }
  }
}
```

If the saved session is missing or expired, tools return an error telling you to run `ancestry_session login`
(it opens Chrome for a one-time sign-in and closes it afterwards). Ancestry's login cookie lasts a long time, so
this is rare; the server also persists any rotated cookies it receives.

## Tools

Thirteen tools, one per resource, each with an `action` parameter. This keeps the definitions small
(about 4K tokens instead of 10K for one-tool-per-endpoint) and tool selection reliable.

| Tool | Actions |
|---|---|
| `ancestry_session` | status, login |
| `tree` | list, get, create, update, set_privacy, export_gedcom, import_gedcom, delete |
| `person` | list, find, get, family_view, relationship_to_home, add, link_existing, update, change_relationship, remove_relationship, delete |
| `fact` | list_types, add, edit, delete, attach_citation, detach_citation, attach_media, detach_media |
| `source` | list_sources, create_source, update_source, create_repository, link_repository, unlink_repository, create_citation, update_citation, get_citation, remove_citation, add_web_link, remove_web_link |
| `notes_tags` | get_notes, save_notes, list_tags, add_tags, remove_tags, create_custom_tag |
| `search_records` | (single action; name/event/relative/place/exactness parameters) |
| `record` | get, image_index, download_image, save_to_person (update/alternate/name/relatives like the Review page), suggest_places, shoebox_list, shoebox_save, shoebox_remove |
| `hint` | summary, list, compare, set_state |
| `media` | list, get, download, upload, update, set_profile_photo, copy_from_tree, delete |
| `dna` | tests, matches (all website filters: cM, parent side, trees, groups, name, unviewed/notes/new, sort), groups, add_to_group, remove_from_group, match_detail, set_note, ethnicity |
| `messages` | list_conversations, get_messages, member_profile, send, notifications |
| `raw_request` | any ancestry.com request with the saved session |

Files: `record.download_image`, `media.download`, and `tree.export_gedcom` write to a local `outPath` (or return
base64); `media.upload` and `tree.import_gedcom` read from a local `filePath`.

Ids: `treeId` from `tree.list`; `personId` is the plain numeric id (not the `pid:1030:tree` form);
`assertionId`, `citationId`, `webLinkId` come from `person.get`. Missing required fields for an action
return an error naming them. Responses are trimmed to what a caller acts on and truncated at 60K chars.

Tests: `pnpm mcp-test` (read-only, prints definition size and latency) and `pnpm mcp-write-test`
(every write action on a throwaway tree that it deletes afterward).

## Repository layout

- `src/http.ts` — Chrome-impersonating HTTP client (impit), CSRF tokens, JSONP, throttling, Cloudflare detection
- `src/session.ts` — cookie jar persisted in `.session.json`
- `src/browser.ts` — Chrome bootstrap used only by `login` (sign in, export cookies, close)
- `src/client.ts` — typed client for every endpoint
- `src/tools.ts` — MCP tool definitions
- `src/server.ts` — stdio entry point
- `scripts/` — `login.ts`, the Chrome launcher, the traffic recorder used during reverse engineering, and the two test suites
- `test-fixtures/` — tiny image and GEDCOM used by the tests
- `docs/` — research notes and the endpoint contracts

## Not covered

Stories (a separate slide-editor app), tree sharing and invitations, merging duplicate people, and comments. Everything
else visible in the Ancestry UI has a tool; `raw_request` covers the rest.

## Caveats

- Ancestry's terms of service restrict automated access. This is a personal tool for your own account and
  trees; use it accordingly. Writes are serialized with a small delay to stay gentle.
- `search_records` mirrors the website's full form: per-name match level, per-event year tolerance and place scope, exact relatives/keyword, collection focus, and a passthrough for collection-specific fields.
- The endpoints are internal and can change without notice. `pnpm mcp-test` is a quick regression check.
- `.session.json`, `.profile/` and `captures/` hold live session cookies and are gitignored. Never commit them.
- Tests run against your own account: `pnpm mcp-test` is read-only (set `ANCESTRY_TEST_TREE` to choose the
  tree, else your first tree is used); `pnpm mcp-write-test` creates and deletes a throwaway tree and briefly
  sets and clears a note on one DNA match that had none.