Skip to main content
Glama
README.md
# Raisa — family history MCP for your own AI assistant

Raisa is an [MCP](https://modelcontextprotocol.io) server for genealogy research in the former USSR and the Russian
Empire. Plug it into Claude, ChatGPT, Gemini, Cursor or any assistant that takes MCP connectors: your assistant does
the thinking and reads the documents; Raisa gives it archive searches, a family tree that is kept between
conversations, and a private family page with a timeline and a story on a map.

Part of **Kin**, a family-history project. The story of the project: https://igor.diy/kin/

## Use it

**Hosted, nothing to install.** Press “Get my link” on https://igor.diy/kin/app/ and add the link to your assistant as
a connector ([guide for each assistant](https://igor.diy/kin/app/connect)). Free; your family's data is kept on that
server under your link, and you can delete it any time by asking your assistant.

**On your own computer.** Your family stays in a folder on your machine (`~/.raisa`).

```bash
git clone https://github.com/igorkauf/raisa-mcp && cd raisa-mcp
python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
```

Then add a local (stdio) MCP server to your assistant, for example in Claude Desktop's `claude_desktop_config.json`:

```json
{"mcpServers": {"raisa": {"command": "/full/path/to/raisa-mcp/.venv/bin/python",
                          "args": ["-m", "kin.mcp_local"], "cwd": "/full/path/to/raisa-mcp",
                          "env": {"KIN_LANG": "en"}}}}
```

or in Claude Code: `claude mcp add raisa -- /full/path/to/raisa-mcp/.venv/bin/python -m kin.mcp_local`
(run from the repository folder). `KIN_LANG` is `en`, `ru` or `uk`; `KIN_DATA` moves the data folder.

Then write to your assistant: *“Raisa, help me find my relatives. My grandfather was …”*

## What it can do

- **Search archives**: Soviet WWII records (OBD Memorial), lists of repression victims (Open List), scanned parish
  and civil registers on Wikimedia Commons, read page by page as images.
- **Know where to look**: a handbook of sources for archives in Ukraine, Russia, Belarus, Poland and beyond
  (`source_guide`).
- **Keep the evidence**: people, findings with their sources, namesakes kept apart, family memories, questions for
  relatives, letters to archives.
- **Build a family page**: tree, timeline, documents and an animated story on a map, written by your assistant
  (`story_inputs` → `save_story` → `build_page`).

It never calls a paid model and never handles passwords or CAPTCHAs. It does not look for living people.

## Raisa and Denis Shiryaev's skill

Raisa's research rules and source handbook come from Denis Shiryaev's open skill
[ex-ussr-kinship-research](https://github.com/DenisSergeevitch/ex-ussr-kinship-research) (MIT licence, included in
`kin/guide/`). Thank you, Denis.

- **The skill** is instructions and a handbook: it teaches an assistant how to research, and the assistant does the
  work itself in apps that load skills, keeping its notes in files.
- **Raisa (MCP)** carries the same rules and handbook, plus working tools: archive searches, scan reading, a tree and
  findings stored between conversations, and the family page. It works in any assistant that takes MCP connectors.

## Code

`kin/mcp_remote.py` is the MCP server (streamable HTTP, one family per link; `kin/mcp_local.py` runs the same tools
over stdio for one family). `kin/tools.py` holds the tools, `kin/adapters/` the archive sources, `kin/site/` the
family page, `kin/guide/` the rules and handbook. Tests: `.venv/bin/pip install pytest httpx && .venv/bin/pytest`.

## Licence

MIT, see `LICENSE`. The handbook in `kin/guide/refs/` is from ex-ussr-kinship-research, MIT, © 2026 Denis Shiryaev.