mcp-grampsweb

mcp-grampsweb

An MCP (Model Context Protocol) server for interacting with Gramps Web genealogy API. This allows AI assistants like Claude to search, retrieve, and create genealogical records in your Gramps Web instance.

Installation

npx mcp-grampsweb

Or install globally:

npm install -g mcp-grampsweb

Configuration

The server requires the following environment variables:

| Variable | Description | Required | |----------|-------------|----------| | GRAMPS_API_URL | Base URL of your Gramps Web instance (e.g., https://gramps.example.com) | Yes | | GRAMPS_USERNAME | Your Gramps Web username | Yes | | GRAMPS_PASSWORD | Your Gramps Web password | Yes | | GRAMPS_TREE_ID | Tree ID for multi-tree instances (requests use /api/trees/{id}/...) | No |

Usage with Claude Desktop

Add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "grampsweb": {
      "command": "npx",
      "args": ["mcp-grampsweb"],
      "env": {
        "GRAMPS_API_URL": "https://your-gramps-web.com",
        "GRAMPS_USERNAME": "your-username",
        "GRAMPS_PASSWORD": "your-password",
        "GRAMPS_TREE_ID": "optional-tree-id"
      }
    }
  }
}

Available Tools

Search & Retrieval

| Tool | Description | |------|-------------| | gramps_search | GQL-based search for any entity type (people, families, events, places, etc.) | | gramps_find | Full-text search across all records | | gramps_get | Get full entity details by handle or Gramps ID |

Data Management

| Tool | Description | |------|-------------| | gramps_create_person | Create a new person record | | gramps_create_family | Create a new family unit | | gramps_create_event | Create a new life event (birth, death, marriage, etc.) | | gramps_create_place | Create a new geographic location | | gramps_create_source | Create a new source document | | gramps_create_citation | Create a new citation | | gramps_create_note | Create a new textual note | | gramps_create_media | Create a new media object | | gramps_create_repository | Create a new repository |

Analysis

| Tool | Description | |------|-------------| | gramps_tree_stats | Get tree statistics (counts of all entity types) | | gramps_get_ancestors | Find ancestors of a person (up to 10 generations) | | gramps_get_descendants | Find descendants of a person (up to 10 generations) | | gramps_recent_changes | Get recently modified records |

Examples

Search for people with a specific surname

Use gramps_search to find people with surname "Smith"

Get ancestors of a person

Find the ancestors of person with handle "abc123" going back 4 generations

Create a new person

Create a person named John Smith, male gender

Development

# Clone the repository
git clone https://github.com/nikkoxgonzales/mcp-grampsweb.git
cd mcp-grampsweb

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Run in development mode
npm run dev

Testing with MCP Inspector

npx @modelcontextprotocol/inspector node dist/index.js

License

MIT