Raisa
by igorkauf
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.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessOutdated data