MCP Hub
Back to servers

Kerykeion MCP Server

An astrological chart generation engine that creates natal, synastry, and transit charts in text, SVG, and PNG formats with support for multiple house systems and languages.

glama
APIs & ServicesData & AnalyticsProductivity
Tools
9
Updated
Jan 6, 2026
View Source
Claim this server

Kerykeion MCP Server

An MCP (Model Context Protocol) server for astrological chart generation using the Kerykeion library. Compatible with Claude Desktop and ChatGPT Desktop.

Features

  • Natal Charts - Birth chart generation with planetary positions, aspects, and house placements
  • Synastry Charts - Relationship compatibility analysis between two people
  • Transit Charts - Current transits to natal positions
  • Composite Charts - Midpoint composite for relationship dynamics
  • Planetary Returns - Solar, Lunar, and other planetary return charts
  • Event Charts - Charts for specific moments (electional, horary)
  • Current Positions - Quick lookup of current planetary positions

Output Formats

  • Text - AI-readable descriptions optimized for LLM interpretation
  • SVG - Vector chart images saved to files (path returned in response)
  • PNG - High-resolution (1600px) raster images (requires cairosvg)

Installation

Using uv (Recommended)

cd kerykeion-mcp
uv sync

Using pip

pip install -e .

System Dependencies for PNG Support

For PNG conversion, you need Cairo graphics library:

# Ubuntu/Debian
sudo apt install libcairo2-dev

# macOS
brew install cairo

# Windows - See cairosvg documentation

Usage

Development Mode (MCP Inspector)

uv run mcp dev src/kerykeion_mcp/server.py

Then open the MCP Inspector at http://localhost:8000/mcp to test tools.

Claude Desktop Configuration

Add to your Claude Desktop config file:

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

{
  "mcpServers": {
    "kerykeion-charts": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "/path/to/kerykeion-mcp",
        "python", "-m", "kerykeion_mcp.server"
      ]
    }
  }
}

Or install directly:

uv run mcp install src/kerykeion_mcp/server.py --name "Kerykeion Charts"

ChatGPT Desktop Configuration

Important: ChatGPT requires HTTPS URLs for MCP connectors. You'll need to tunnel your local server.

  1. Start the server with SSE transport:

    uv run python -m kerykeion_mcp.server --sse

    Server runs at http://localhost:8000/sse

  2. Create an HTTPS tunnel using ngrok (or similar):

    ngrok http 8000

    You'll get a URL like: https://abc123.ngrok-free.app

  3. Add to ChatGPT:

    • Enable Developer Mode: Settings → Connectors → Advanced → Developer mode
    • Add MCP Server URL: https://abc123.ngrok-free.app/sse

Available Tools

ToolDescription
generate_natal_chartCreate a birth chart
generate_synastry_chartRelationship compatibility analysis
generate_transit_chartCurrent or specified transits to natal
generate_composite_chartMidpoint composite for a couple
generate_planetary_returnSolar/Lunar returns
generate_event_chartChart for any specific moment
get_current_positionsCurrent planetary positions (text only)
get_aspectsGet natal chart aspects without images
get_synastry_aspectsGet inter-chart aspects for compatibility

Common Parameters

All chart tools accept:

  • lat/lng: Coordinates (positive N/E, negative S/W)
  • tz_str: IANA timezone (e.g., "Europe/Rome", "America/New_York")
  • theme: "classic", "light", "dark", "strawberry", "dark-high-contrast"
  • language: "EN" (default), "IT", "FR", "ES", "PT", "CN", "RU", "TR", "DE", "HI"
  • house_system: "P" (Placidus), "W" (Whole Sign), "K" (Koch), "M" (Morinus), etc.
  • output_format: "text", "images", or "all"
  • output_dir: Custom directory to save chart images (optional)
  • chart_style: "full" (default), "wheel_only", or "aspect_grid"

Response Format

All chart tools return a compact response (~1KB) with file paths:

{
  "status": "success",
  "summary": "Chart generated successfully. SVG: /path/to/file.svg, PNG: /path/to/file.png",
  "chart_type": "Natal",
  "subject_name": "Test",
  "text": "AI-readable chart analysis...",
  "svg_path": "/home/user/.kerykeion_charts/natal_test_20260106.svg",
  "png_path": "/home/user/.kerykeion_charts/natal_test_20260106.png",
  "output_dir": "/home/user/.kerykeion_charts"
}

Note: Chart content is saved to files rather than returned inline. This keeps responses small and prevents MCP clients from showing "Tool result too large" messages. The AI assistant can read SVG files directly if needed for embedding.

Embedding Charts in Claude Artifacts

Method 1: Read SVG File (Recommended)

The AI assistant can read the SVG file directly from svg_path and embed it:

<html>
<body>
<!-- SVG content read from svg_path file -->
</body>
</html>

Result: Interactive, scalable vector chart in artifact.

Method 2: PNG with File Path

Response includes png_path for local file linking:

![Chart](https://raw.githubusercontent.com/jasperb3/kerykeion-mcp/main/file:///C:/Users/.../chart.png)

Download the markdown file - image renders from local path.

Example Usage

Ask Claude or ChatGPT:

"Generate a natal chart for someone born June 15, 1990 at 2:30 PM in Rome (lat: 41.9028, lng: 12.4964, timezone: Europe/Rome)"

"Create a synastry chart comparing Person A (born Jan 1, 1985 in NYC) and Person B (born Dec 25, 1987 in London)"

"What are the current planetary transits to my natal chart?"

Prompts

The server includes pre-defined prompts to guide conversations:

  • natal_chart_prompt - Template for creating natal charts
  • synastry_prompt - Template for relationship compatibility
  • transit_prompt - Template for transit analysis

License

MIT

Reviews

No reviews yet

Sign in to write a review