Gramps Web MCP Server

A Model Context Protocol (MCP) server that exposes the Gramps Web HTTP API as a set of MCP tools for AI assistants.

Features

• Complete CRUD operations for People, Families, Events, and Places
• Tree navigation helpers (ancestors, descendants, family relationships)
• Health checking and API metadata
• Read-only mode support
• Comprehensive error handling with structured MCP errors
• Full TypeScript implementation with Zod schema validation

Installation

# Install dependencies
pnpm install

# Build the project
pnpm run build

Configuration

Configure via environment variables:

• GRAMPS_WEB_BASE_URL (required) - Base URL of Gramps Web API (e.g., https://my-gramps/api)
• GRAMPS_WEB_AUTH (recommended) - Username and password in username:password format; uses JWT token flow with automatic refresh
• GRAMPS_WEB_API_TOKEN (optional) - Static bearer token (bypasses JWT flow)
• GRAMPS_WEB_TREE_ID (optional) - Default tree ID if API supports multiple trees
• GRAMPS_WEB_REQUEST_TIMEOUT_MS (optional, default: 15000) - HTTP timeout in milliseconds
• GRAMPS_WEB_VERIFY_TLS (optional, default: true) - Set to "false" to disable TLS verification
• GRAMPS_WEB_READ_ONLY (optional, default: false) - Set to "true" to disable mutation operations

Usage

As MCP Server

# Start the server (uses stdio transport)
node dist/index.js

As OpenClaw Skill

# Use the CLI version for OpenClaw integration
node dist/cli.js

Development

# Run in development mode
pnpm run dev

# Type check without building
pnpm run typecheck

Available Tools

Health & Metadata

• gramps_health - Check API connectivity and get metadata

People Management

• gramps_list_people - List people with filters and pagination
• gramps_get_person - Get person by handle or Gramps ID
• gramps_search_people - Full-text search across people
• gramps_create_person - Create new person record
• gramps_update_person - Update existing person
• gramps_delete_person - Delete person by handle

Family Management

• gramps_list_families - List family units
• gramps_get_family - Get family by handle or Gramps ID
• gramps_create_family - Create family linking parents and children
• gramps_update_family - Update family relationships

Event Management

• gramps_list_events - List events with optional type filter
• gramps_get_event - Get event by handle or Gramps ID
• gramps_create_event - Create new event record

Place Management

• gramps_list_places - List places with optional query filter
• gramps_get_place - Get place by handle or Gramps ID
• gramps_create_place - Create new place record

Tree Navigation

• gramps_get_person_with_family - Get person with immediate family records
• gramps_get_ancestors - Get ancestors up to specified generations
• gramps_get_descendants - Get descendants up to specified generations

Error Handling

The server maps HTTP errors to structured MCP errors:

• NOT_FOUND - Resource not found (HTTP 404)
• VALIDATION - Invalid input or validation error (HTTP 400, 422)
• AUTH - Authentication/authorization error (HTTP 401, 403)
• SERVER - Server error or network issues (HTTP 5xx, timeouts)

License

ISC