# findagrave-com-mcp

An MCP server for [Find a Grave](https://www.findagrave.com). It searches and reads memorials: birth and death dates
and places, burial cemetery, plot, inscription, biography, linked parents/spouses/children/siblings, photos and
flowers. It also covers cemeteries and Find a Grave's place hierarchy.

It calls the site's own GraphQL API (`POST https://www.findagrave.com/orc/graphql`). The API answers anonymously, so
no login, cookies or browser are involved. Everything is read-only.

## Tools

| Tool | Actions | What for |
|---|---|---|
| `findagrave_memorial` | `search`, `get`, `photos`, `flowers` | Find people. Read a memorial in full: maiden name kept separate, family grouped by role with each relative's memorial id, photos, the matching Ancestry "Find a Grave Index" record, and a ready citation. |
| `findagrave_cemetery` | `search`, `get` | Find cemeteries by name and/or place, and read one. List a cemetery's burials with `findagrave_memorial search` + `cemeteryId`. |
| `findagrave_place` | `search`, `get`, `children` | Place ids (`county_2452` …) for narrowing searches, and the counties or towns inside a place. |
| `findagrave_download` | `photo` | A gravestone, portrait or clipping photo, returned inline (scaled) or written to a file. |
| `findagrave_graphql` | `query` | A raw read-only GraphQL query for anything the other tools lack. Mutations are refused. |

What the search defaults do, and why (each was checked against the website's counts; see `docs/endpoints.md`):
- **Names match exactly.** Find a Grave's own default is a prefix match, so "Hunt" also finds Hunter and Huntley.
  `nameMatch: "prefix"` restores it (useful for initials) and `"similar"` adds spelling variants.
- **Maiden names are included,** so a married woman is found under her birth surname.
- **Location text is resolved to one place by name** and reported back. The site's typeahead ranks
  "Newton, Mississippi" as Newton County and "Rijeka, Croatia" as a village in Lika. Text that fits several places is
  refused with their ids.
- `relativeName` switches names to prefix matching and says so. With exact matching the site finds a relative only
  by the relative's whole stored name, maiden name included.

## Setup

```bash
pnpm install
```

`.mcp.json`:

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

Requirements: Node 26+ (runs TypeScript directly) and pnpm; no browser. `sharp` scales photos for inline viewing.
`FINDAGRAVE_MIN_INTERVAL_MS` (default 250) spaces requests, because the site's Cloudflare protection challenges
bursts.

## Tests

- `pnpm test`: unit tests on recorded responses (`test/fixtures`, re-recorded with `node scripts/record-fixtures.ts`).
  No network.
- `pnpm mcp-test`: live, over stdio. It calls every action and error path, checks result sizes, and runs a count
  comparison for every search filter: a real value must narrow the total and a nonsense value must give about zero.
- `pnpm typecheck`.

## Caveats

- Find a Grave is contributor-written. Dates, family links and biographies are claims, often unsourced and sometimes
  copied from online trees. Prefer what a stone in a photo shows, and cite the memorial (`get` returns the citation
  the site prints).
- A search reaches only its first 10,000 results and returns at most 50 rows per call. Narrow by place, years or
  cemetery.
- A recently deceased person's memorial can be shown with limited details (`limitedDisplay`).