Gramps MCP Server

Проект

MCP-сервер, который предоставляет AI-агентам, таким как opencode, Claude, Cursor и другим MCP-клиентам, полный набор возможностей Gramps Web API. Сервер опубликован на PyPI как gramps-mcp-full.

Gramps — бесплатная программа с открытым исходным кодом для генеалогических исследований. Gramps Web включает REST API (gramps-web-api), позволяющий читать данные семейного дерева и работать с ними: людьми, семьями, событиями, местами, источниками, ссылками на источники, заметками, медиафайлами, хранилищами и тегами. Кроме того, API поддерживает генеалогические вычисления (объединение записей, временные шкалы, родственные связи, оценка статуса жизни, анализ ДНК), импорт и экспорт, отчёты, транзакции и администрирование сервера.

Сервер позволяет агенту напрямую запрашивать данные дерева Gramps и работать с ними: выполнять полный CRUD для всех типов объектов, полнотекстовый и семантический поиск, объединять объекты (с сохранением «Феникса» или «Титаника»), строить временные шкалы и родственные связи, оценивать, жив ли человек, анализировать совпадения ДНК, обрабатывать медиафайлы (загружать и скачивать файлы, создавать миниатюры, распознавать текст и лица), импортировать и экспортировать GEDCOM / Gramps XML с фильтрами конфиденциальности, формировать отчёты, выполнять транзакции с произвольными данными и администрировать пользователей, деревья, закладки и словари типов. Поддерживается работа с несколькими экземплярами: можно указать один или несколько базовых URL Gramps Web и настроить аутентификацию с помощью токена/JWT.

⚠️ Официальный API, изменяемые данные. В отличие от сервера EduPage, который использует обратную разработку недокументированных конечных точек, этот сервер работает с официальным документированным REST API Gramps Web — gramps-web-api, который поддерживается организацией gramps-project и имеет опубликованную спецификацию OpenAPI по адресу https://gramps-project.github.io/gramps-web-api/. Функции чтения можно использовать свободно. Функции записи (manage_*, merge_objects, manage_import, manage_transaction, …) следует применять осторожно: они изменяют реальные данные дерева.

Содержание

Зачем нужен ещё один Gramps MCP Server?
Возможности
Начало работы
- Предварительные требования
- 1. Установка
- 1. Настройка учётных данных
- 1. Регистрация в MCP-клиенте
Примеры запросов
Несколько экземпляров (базовые URL)
Справочник по инструментам
Данные и безопасность
Участие в разработке
Ограничения
Поддержка
Лицензия

Зачем нужен ещё один Gramps MCP Server?

Уже существуют другие Gramps MCP-серверы:

Knuckles-Team/gramps-mcp — 35 инструментов с маршрутизацией по действиям, агент A2A, телеметрия OTEL, один GRAMPS_URL
cabout-me/gramps-mcp — 16 инструментов, AGPL-3.0, основан на Docker Compose, ориентирован на HTTP
Scormave/gramps-web-mcp — 57 инструментов и 6 ресурсов, .NET, поддержка нескольких транспортов, режим только для чтения
Genealogy-MCP/gramps-mcp — AGPLv3, зеркало на GitLab, 32 выпуска

Все эти проекты заслуживают внимания, и я не связан ни с одним из них: они приведены здесь только для объективного сравнения. В одних проектах функциональность разбита на множество почти одинаковых инструментов, другие охватывают лишь преимущественно операции чтения API.

Этот проект намеренно предлагает больше возможностей:

Возможность	Knuckles-Team/gramps-mcp	cabout-me/gramps-mcp	Scormave/gramps-web-mcp	этот проект
Полный CRUD — люди, семьи, события, места, источники, ссылки на источники, заметки, медиафайлы, хранилища, теги	частично (через действия)	частично	✅	✅
Один инструмент `manage_*` на каждый тип объекта (`action=`: get/list/create/update/delete)	❌	❌	❌	✅
Генеалогические вычисления — `merge_objects` (с сохранением «Феникса» или «Титаника»), `get_timeline`, `get_relation`, `get_living`	❌	❌	частично	✅
Анализ ДНК — `analyze_dna` (совпадения, Y-ДНК, анализатор сегментов)	❌	❌	❌	✅
Обработка медиафайлов — загрузка бинарных данных, скачивание файлов, миниатюры, распознавание текста и лиц	❌	частично	частично	✅
Импорт / экспорт — GEDCOM / Gramps XML с предварительным запуском без изменений, восстановлением и фильтрами конфиденциальности	только импорт	только импорт	только экспорт	✅
Отчёты — просмотр списка, создание и скачивание	❌	❌	❌	✅
Транзакции — применение и отмена исходных данных, история, массовое создание и удаление	❌	❌	❌	✅
Администрирование — пользователи, деревья (исправление / миграция / проверка / конфигурация), закладки, типы	частично	❌	частично	✅
Метаданные сервера — база данных, версии, локаль, количество объектов, возможности	❌	❌	❌	✅
Несколько экземпляров — один или несколько базовых URL Gramps Web	❌	❌	✅	✅
Аутентификация — отложенный вход по токену `/api/token/`, заранее выданные JWT и обновление токена	JWT	имя пользователя/пароль	токен	✅
Режим только для чтения	❌	❌	✅	✅
Проверки качества по умолчанию — py_compile, проверка связи с Docker MCP, проверка HTTP-аутентификации, Trivy, контроль Glama TDQS	❌	❌	❌	✅
Публикация — PyPI, GHCR, MCP Registry, Glama	PyPI	Docker Hub/GitHub	GHCR	✅

Ключевые отличия:

Компактный набор инструментов с точными параметрами. 27 инструментов (в сравнении с 57 раздробленными или 35 маршрутизируемыми по действиям): для каждого типа объекта предусмотрен один инструмент manage_* с параметром action=, по образцу стандартного набора get_timetable/login.
Генеалогические вычисления. Объединение записей с сохранением «Феникса» или «Титаника», хронологические временные шкалы, степени родства и пути между людьми, оценка статуса жизни с вероятными датами, а также полноценный анализатор сегментов ДНК — сервер не ограничивается хранением объектов.
Полный набор операций записи. Импорт и экспорт с фильтрами конфиденциальности и предварительным запуском без изменений, создание отчётов, транзакции с исходными данными, администрирование пользователей, деревьев, закладок и типов — другие серверы этих возможностей не предоставляют.
Готовность к промышленной эксплуатации. Поддержка нескольких экземпляров, аутентификация по токену/JWT с обновлением токена, проверки качества для каждого PR (lint → проверка связи с Docker → проверка HTTP-аутентификации → Trivy → контроль Glama TDQS), а также публикация через OIDC в PyPI, GHCR и MCP Registry.

Возможности

Один MCP-сервер предоставляет 27 инструментов (опубликован на PyPI как gramps-mcp-full):

Основные — ping (проверка работоспособности), get_instances (список настроенных базовых URL Gramps Web)
Объекты (полный CRUD) — manage_person, manage_family, manage_event, manage_place, manage_source, manage_citation, manage_note, manage_media, manage_repository, manage_tag. Каждый инструмент принимает один параметр action= (get, list, create, update, delete); manage_media также поддерживает загрузку бинарных данных, скачивание файлов, создание миниатюр, распознавание текста и лиц
Поиск и вычисления — search (полнотекстовый и семантический поиск с фильтрацией по типу объекта), merge_objects (по умолчанию сохраняется «Феникс», по желанию — «Титаник»), get_timeline (для человека, семьи или дерева), get_relation (степень родства и пути), get_living (статус или вероятные даты), analyze_dna (совпадения, Y-ДНК, анализатор сегментов)
Управление данными — manage_import (список средств импорта, импорт файла с предварительным запуском без изменений, восстановление резервной копии), manage_export (список средств экспорта, экспорт GEDCOM/Gramps XML/CSV с фильтрами конфиденциальности), manage_report (просмотр списка, создание и скачивание отчётов), manage_transaction (применение и отмена исходных данных, просмотр истории, массовое создание и удаление)
Администрирование — manage_user, manage_tree (создание, обновление, отключение, включение, исправление, миграция, проверка и настройка), manage_bookmark (для каждого пространства имён), manage_type (стандартные и пользовательские словари), get_server_info (база данных, версии, локаль, количество объектов, возможности)

Начало работы

Вам понадобятся MCP-совместимый клиент (opencode, Claude Desktop, Cursor и т. д.) и доступный экземпляр Gramps Web (базовый URL и учётная запись пользователя с необходимыми разрешениями).

1. Установка

Если вы используете AI-клиент для программирования, чтобы начать работу, часто достаточно простого запроса, например: «Установи Gramps MCP согласно инструкциям в репозитории GitHub oliverhruby/gramps-mcp». Большинство клиентов с поддержкой MCP помогут выбрать подходящий вариант настройки.

Вариант A — из MCP Registry (рекомендуется; установка в один клик в VS Code / GitHub Copilot)

Сервер опубликован в MCP Registry. В VS Code или GitHub Copilot найдите «Gramps MCP» и установите его одним нажатием. Также можно воспользоваться прямой ссылкой: mcp://install/io.github.oliverhruby/gramps-mcp

Вариант B — из PyPI

Выберите этот вариант для обычного использования выпущенной версии.

Требования: uv для запуска через uvx или Python 3.10+ для pip.

uvx gramps-mcp-full
# or, if you prefer pip (into whatever environment your MCP client uses):
pip install gramps-mcp-full

uvx запускает пакет без постоянной установки. Если uvx недоступен, сначала установите uv (pip install uv или winget install astral-sh.uv).

Вариант C — из GitHub (последняя версия исходного кода)

Выберите этот вариант, если хотите получить последние изменения до выхода версии на PyPI.

Требования: uv для запуска через uvx или Python 3.10+ для pip.

uvx --from "git+https://github.com/oliverhruby/gramps-mcp.git" gramps-mcp-full
# or
pip install "git+https://github.com/oliverhruby/gramps-mcp.git"

Вариант D — Docker

Выберите этот вариант для запуска в изолированном контейнере.

Требования: Docker.

Загрузите готовый образ (рекомендуется):

docker pull ghcr.io/oliverhruby/gramps-mcp:latest

docker run --rm -i \
  -e GRAMPS_MCP_INSTANCES=https://gw.example.com \
  -e GRAMPS_MCP_USERNAME=your_username \
  -e GRAMPS_MCP_PASSWORD=your_password \
  ghcr.io/oliverhruby/gramps-mcp:latest

Также доступны образы с указанием версии, например v0.1.0, если вы хотите зафиксировать конкретную версию.

Соберите образ локально из исходного кода (резервный вариант):

docker build -t gramps-mcp-full .

docker run --rm -i \
  -e GRAMPS_MCP_INSTANCES=https://gw.example.com \
  -e GRAMPS_MCP_USERNAME=your_username \
  -e GRAMPS_MCP_PASSWORD=your_password \
  gramps-mcp-full

Контейнер использует те же переменные окружения, что описаны в разделе «Настройка учетных данных». Он также включает HEALTHCHECK (по умолчанию проверяется доступность процесса stdio; в режимах HTTP-транспорта выполняется локальная проверка TCP).

Для HTTP-транспорта задайте необязательные переменные среды выполнения:

MCP_TRANSPORT: stdio (по умолчанию), sse или streamable-http
MCP_HOST: адрес привязки (по умолчанию 127.0.0.1)
MCP_PORT: порт привязки (по умолчанию 8000)
MCP_API_KEY: необязательный bearer-токен для аутентификации HTTP-запросов

Если задан MCP_API_KEY, HTTP-запросы должны содержать заголовок Authorization: Bearer . Если MCP_API_KEY не задан, аутентификация HTTP-конечных точек не выполняется. Для рабочей среды рекомендуется настроить надлежащую аутентификацию и TLS через reverse proxy или API gateway.

В pyproject.toml закреплена версия mcp. Укажите учетные данные в оболочке или переменных окружения (либо в файле .env) и передавайте их с помощью {env:VAR} или задайте непосредственно в блоке env:. При первом запуске uvx автоматически подготовит пакет; команда должна быть доступна через PATH.

Claude Desktop / Cursor — используйте claude_desktop_config.json / .mcp.json со стандартной записью mcpServers: укажите в command/args путь к Python из виртуального окружения и к файлу gramps_mcp.py, а учетные данные добавьте в блок env.

После изменения конфигурации клиента перезапустите его, чтобы сервер MCP загрузился.

Примеры запросов

Запрос пользователя	Вероятный вызов инструмента	Ожидаемый ответ
«Есть ли подключение и выполнен ли вход?»	`ping` → `get_instances`	Состояние сервера и настроенные экземпляры Gramps Web.
«Перечисли всех людей, родившихся после 1900 года»	`manage_person action="list"`	Краткий список подходящих людей.
«Покажи семейное древо человека I001»	`manage_family action="list"` → `get_timeline handle="I001"`	Семья человека и хронология событий.
«Объедини человека I002 с I001, сохранив данные I001»	`merge_objects obj_type="person" handle1="I001" handle2="I002"`	Подтверждение объединения с сохранением записи I001.
«Как связаны люди I003 и I020?»	`get_relation handle1="I003" handle2="I020"`	Степень родства и путь или пути между ними.
«Вероятно ли, что человек I005 жив?»	`get_living handle="I005"`	Оценка вероятности того, что человек жив, либо примерные даты рождения и смерти.
«Проанализируй совпадения ДНК для человека I010»	`analyze_dna action="matches" handle="I010"`	Совпадения ДНК, гаплогруппа Y-DNA и разобранные сегменты.
«Загрузи медиафайл для человека I012»	`manage_media action="upload" handle="I012" …`	Созданный медиаобъект; доступны миниатюра и OCR.
«Экспортируй древо в GEDCOM с фильтрами конфиденциальности»	`manage_export extension="gedcom" options={"privacy": …}`	Подготовленный для скачивания файл экспорта.
«Импортируй файл GEDCOM, сначала выполнив пробный запуск»	`manage_import action="import" extension="gedcom" file_path="…"`	Отчет о пробном запуске, затем результат импорта.
«Создай исследовательский отчет для человека I018»	`manage_report action="generate" report_id="…"`	Созданный отчет, доступный для скачивания.
«Примени транзакцию с исходными данными, чтобы обновить источник»	`manage_transaction action="apply" payload="…"`	Транзакция применена; позднее ее можно отменить.
«Перечисли всех пользователей, затем отключи `ciowner`»	`manage_user action="list"` → `manage_user action="update" data={…}`	Список пользователей и отключенная учетная запись.
«Создай новое древо и настрой его базовый URL»	`manage_tree action="create" data={…}` → `… action="config_set"`	Новое древо создано и настроено.
«Перечисли все стандартные и пользовательские типы событий и мест»	`manage_type action="all"`	Списки типов для каждого типа объектов.
«Получи метаданные сервера»	`get_server_info`	База данных, версии, локаль, количество объектов и возможности сервера.

Несколько экземпляров (базовые URL)

Каждый экземпляр Gramps Web использует собственную сессию. Настроить несколько экземпляров можно двумя способами.

A) Переменные окружения (рекомендуется). Задайте GRAMPS_MCP_INSTANCES со списком базовых URL, разделенных запятыми, а также общие GRAMPS_MCP_USERNAME / GRAMPS_MCP_PASSWORD. Сервер будет входить в каждый экземпляр при первом обращении к нему:

setx GRAMPS_MCP_INSTANCES "https://gw.example.com,https://gw2.example.com"   # Windows
export GRAMPS_MCP_INSTANCES="https://gw.example.com,https://gw2.example.com" # macOS / Linux

get_instances     # lists both base URLs + login status per instance

Каждый инструмент для работы с данными обращается к активному экземпляру. Вход в каждый экземпляр выполняется при первом обращении к нему через api/token/.

B) Заранее выданные JWT. Задайте GRAMPS_MCP_TOKENS — список токенов, разделенных запятыми, в том же порядке, что и экземпляры в GRAMPS_MCP_INSTANCES. Сессии будут созданы напрямую, без входа через api/token/ по запросу.

Используете один экземпляр? Достаточно задать GRAMPS_MCP_INSTANCES, USERNAME и PASSWORD. Для нескольких экземпляров добавьте их в список через запятую (автоматический вход) или укажите GRAMPS_MCP_TOKENS.

Справочник по инструментам

Инструмент	Описание	Запись?
`ping`	Проверка работоспособности.	💡 чтение
`get_instances`	Список настроенных экземпляров Gramps Web.	💡 чтение
`manage_person`	CRUD-операции с записями Person (`action` = get/list/create/update/delete).	✅ создание/обновление/удаление
`manage_family`	CRUD-операции с записями Family (связи отца, матери и детей поддерживаются на стороне upstream).	✅ создание/обновление/удаление
`manage_event`	CRUD-операции с записями Event (типы берутся из `manage_type`).	✅ создание/обновление/удаление
`manage_place`	CRUD-операции с записями Place.	✅ создание/обновление/удаление
`manage_source`	CRUD-операции с записями Source.	✅ создание/обновление/удаление
`manage_citation`	CRUD-операции с записями Citation (связь с `source_handle`).	✅ создание/обновление/удаление
`manage_note`	CRUD-операции с записями Note (хранят строки сегментов DNA, текст и другие данные).	✅ создание/обновление/удаление
`manage_media`	CRUD-операции с Media, загрузка бинарных файлов, скачивание файлов, создание миниатюр, OCR и распознавание лиц.	✅ создание/обновление/удаление/загрузка
`manage_repository`	CRUD-операции с записями Repository.	✅ создание/обновление/удаление
`manage_tag`	CRUD-операции с записями Tag.	✅ создание/обновление/удаление
`search`	Полнотекстовый или семантический поиск с фильтрацией по типу объекта.	💡 чтение
`merge_objects`	Объединение двух объектов одного типа в один.	✅ объединение
`get_timeline`	Хронология событий для человека, семьи или всего дерева.	💡 чтение
`get_relation`	Определение родственной связи между двумя людьми.	💡 чтение
`get_living`	Оценка того, жив ли человек, или определение периода, до которого он мог быть жив.	💡 чтение
`analyze_dna`	Анализ совпадений DNA и разбор исходных строк совпадений.	✅ только разбор
`manage_import`	Список доступных импортёров или импорт файла (Gramps XML, GEDCOM и др.); пробный запуск и восстановление.	✅ файл/восстановление
`manage_export`	Список доступных экспортёров или создание экспорта (GEDCOM, Gramps XML и др.); фильтры конфиденциальности.	✅ запуск
`manage_report`	Список, настройка или создание отчётов (PDF, текст, веб и др.).	✅ запуск
`manage_transaction`	Применение транзакций к исходной БД, просмотр истории отмены или массовое создание/удаление.	✅ все действия
`manage_user`	Администрирование пользователей Gramps Web (создание, обновление, удаление, смена пароля).	✅ все действия
`manage_tree`	Деревья: создание и обновление, отключение и включение, восстановление, миграция, проверка и настройка.	✅ все действия
`manage_bookmark`	Чтение и редактирование закладок в пространствах имён объектов.	✅ добавление/удаление
`manage_type`	Список словарей типов Gramps (пользовательских и стандартных) для всех типов объектов.	💡 чтение
`get_server_info`	Получение сведений о сервере, базе данных, локали и количестве объектов.	💡 чтение

Метки ✅ «запись» и 💡 «чтение» взяты из docstring каждого инструмента (правило 4 в AGENTS.md).

Данные и безопасность

Большинство инструментов поддерживают чтение и запись через action=. Действия записи (отмеченные ✅ выше) изменяют реальные данные дерева Gramps. Используйте их осторожно и, если возможно, сначала выполняйте пробный запуск (manage_import dry-run, предварительный просмотр экспорта) перед потенциально разрушительными операциями.
По умолчанию при merge_objects сохраняется объект в режиме phoenix (уцелевший объект сохраняет свой handle); для сохранения объекта в режиме titanic передайте соответствующую опцию. Отменить объединение нельзя — заранее рассмотрите возможность создать снимок с помощью manage_transaction или экспортную резервную копию.
manage_transaction применяет исходные данные для БД. Ошибочные изменения можно отменить с помощью action="undo", указав возвращённый идентификатор транзакции, но в остальном изменения вносятся непосредственно в дерево.
Сквозной тестовый набор e2e работает с реальными учётными записями и данными. Он никогда не запускается в публичном CI, не фиксирует изменения в репозитории, не записывает в журнал и не загружает идентификационные данные. CI сравнивает только односторонние отпечатки SHA-256; при локальном запуске точные значения хранятся в файлах, исключённых из Git.
При проверке каждого PR выполняются контрольные проверки качества: py_compile, рукопожатие Docker MCP, проверка HTTP-аутентификации, сканирование Trivy и контроль Glama TDQS (оценки инструментов, инвентаризация и общий qualityScore).

Участие в проекте

Рекомендации для участников и сопровождающих проекта приведены в CONTRIBUTING.md.

Процесс внесения изменений и локальная настройка
Архитектура и детали реализации
Процесс выпуска релизов (PyPI, GitHub Releases, GHCR, MCP Registry)
Контрольные проверки качества CI и контроль Glama TDQS
Соглашение: при добавлении или удалении инструментов синхронно обновляйте четыре места: минимальное количество инструментов в quality-gates, GLAMA_EXPECTED_TOOLS, таблицу инструментов и их количество в README, tests/e2e/test_manifest.py

Ограничения

Работа зависит от официального Gramps Web API. Набор доступных полей соответствует REST-схеме upstream-проекта gramps-project/gramps-web-api; в данных объектов используются соглашения Gramps для handle и gramps_id.
Инструменты записи изменяют реальные данные без дополнительного подтверждения. Не запускайте разрушающие вызовы инструментов, если не понимаете их последствий: сервер не добавляет отдельный запрос подтверждения поверх API.
Аутентификация действует в течение всего времени работы процесса. Сессии создаются по запросу для каждого экземпляра через api/token/ и обновляются при необходимости; это не постоянный вход, как в браузере.
OCR и распознавание лиц для Media зависят от дополнительных сервисов Gramps Web. Если они не включены для экземпляра, соответствующие функции manage_media будут ограничены загрузкой и скачиванием файлов.
Ограничения лицензии для одного дерева. Бесплатный тариф Gramps Web исторически ограничивает функции для нескольких пользователей и деревьев; инструменты администрирования (manage_user и некоторые действия manage_tree) требуют тарифного плана с поддержкой этих функций.
MCP_API_KEY защищает только HTTP-транспорт. Для производственной среды завершайте TLS и настраивайте аутентификацию через reverse proxy перед конечной точкой streamable-HTTP.

Поддержка

Если вам нравится этот проект и вы хотите поддержать его или предложить новую функцию, угостите меня пивом: так я смогу расслабиться и придумывать новые идеи :-)

Лицензия

Проект не связан с проектом Gramps и не одобрен им или авторами gramps-web-api. Gramps — товарный знак соответствующих правообладателей.