Kerykeion

You can run a dedicated MCP server for Kerykeion astrology charts to generate natal, synastry, transit, and other chart types. It integrates with compatible MCP clients to produce text descriptions and SVG/PNG charts, saving outputs to files for compact responses and easy embedding.

How to use

Start your MCP server in development mode or via a CLI config, then connect your MCP client to the server endpoint provided by your chosen method. You can request natal charts, synastry analyses, transit charts, composites, planetary returns, and event charts. The server returns concise text analyses and provides paths to generated SVG or PNG chart images you can embed or link.

Typical usage patterns include requesting a natal chart for a person, asking for a synastry comparison between two individuals, or querying current transits to a natal chart. You’ll receive a short, AI-readable text summary and file paths for the SVG and PNG chart images when you specify image output.

How to install

Prerequisites: you need Python and the uv tooling to run the MCP server locally.

Install the MCP server package in editable mode and prepare dependencies.

Run the server in development or production-friendly modes as shown.

# Setup step (example path shown, adapt to your environment)
# If you already have Python and uv installed, skip to the run step
pip install -e .

# Claude Desktop style (local CLI command for the MCP server)
uv run --directory /path/to/kerykeion-mcp python -m kerykeion_mcp.server

# ChatGPT Desktop style (MCP server started with SSE for HTTPS tunneling)
uv run python -m kerykeion_mcp.server --sse

Additional sections

Configuration, security, and usage notes help you tailor the MCP server to your environment. Charts can be saved as SVG for scalable embedding or PNG for quick thumbnails. The server also supports text-only outputs for AI-focused workflows.

Environment and tooling details: you will mainly interact with the MCP server through your client. If you need HTTPS connections for a specific client, set up a tunnel to the local server and provide the secure URL to the client. Use the output paths to embed or link generated charts in your applications.

Troubleshooting tips: ensure required system dependencies for PNG support are installed (Cairo graphics library), confirm the server process is running, and verify the client is configured to reach the correct local or tunneled URL. If charts fail to generate, check the output directory permissions and confirm the requested chart parameters (lat/lng, timezone, house system, language, and output format).

Available tools

generate_natal_chart

Create a birth chart with planetary positions, aspects, and house placements.

generate_synastry_chart

Analyze relationship compatibility by comparing two natal charts.

generate_transit_chart

Generate current or specified transits to natal positions.

generate_composite_chart

Compute a midpoint composite chart for relationship dynamics.

generate_planetary_return

Produce Solar, Lunar, or other planetary return charts.

generate_event_chart

Create charts for specific moments such as elections or horary events.

get_current_positions

Provide current planetary positions in text form.

get_aspects

Return natal chart aspects without embedding images.

get_synastry_aspects

Return inter-chart aspects for compatibility analysis.