The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the GetBirthChart MCP listing page.
Official MCP server 0.2.0 for GetBirthChart astrology calculations. It gives
MCP-compatible AI clients access to structured calculations through the public
GetBirthChart API; it does not contain or reimplement the astrology engine.
Create a key at getbirthchart.com/developers. Keep it private and do not commit MCP host configuration containing the real key.
The package runs over MCP stdio and can be launched with npx:
This is the standard command-based configuration for hosts that support MCP stdio servers. Use your client’s current documentation for the exact configuration file or UI location; this repository has been protocol-tested with the official MCP TypeScript client, not vendor-specific clients.
| Variable | Required | Description |
|---|---|---|
GETBIRTHCHART_API_KEY | Yes | Server-side developer API key. |
GETBIRTHCHART_API_BASE_URL | No | HTTPS API base URL override for development/testing. HTTP is accepted only for localhost. |
The key is read at startup, never accepted as a tool argument, and never written to stdout, logs, resources, or tool results.
All tools are read-only and return structured calculation facts. Inputs use strict fields: date, optional time and place, required latitude, longitude, and timezone, plus optional unknown_time and calculation settings documented below.
| Tool | Input | Output | Exact time required? | Unknown-time behavior |
|---|---|---|---|---|
calculate_birth_chart | birthData | Mapped natal chart | No | Omits Ascendant and houses; preserves uncertainty. |
get_planet_positions | birthData | Planet placements | No | Preserves chart uncertainty. |
get_big_three | birthData | Sun, Moon, and optional Rising | No | Does not guess the Ascendant. |
get_moon_sign | birthData | Moon sign and uncertainty | No | Returns ambiguity when the backend cannot establish one sign. |
get_rising_sign | birthData | Rising sign | Yes | Returns birth_time_required. |
calculate_aspects | birthData | Natal aspects | No | Returns backend-owned facts only. |
calculate_synastry | person_a, person_b, relationship fields | Synastry aspects and summaries | Per person | Preserves each person's unknown-time limits. |
The current public API does not geocode place; provide latitude, longitude,
and an IANA timezone even when a place label is included. The MCP server never
invents a birth time. The backend may use local midnight as the labeled
calculation anchor for an unknown-time assessment, but it never presents that
anchor as the person's birth time and never guesses houses, the Ascendant, or
an ambiguous Moon sign.
Example input:
Unknown time:
The natal tools accept the exposed core gbc-astro 1.13.0 options house_system,
node_type, aspect_preset, custom_aspect_rules, additional_points,
fold, zodiac, and ayanamsa. Omit them for the legacy-compatible defaults:
Tropical, Placidus, True Node, Standard aspects, Chiron on, and Lilith off.
Sidereal calculations require a named ayanamsa; Lahiri is the recommended
product choice. Custom aspects require custom_aspect_rules and each rule uses
type, exact_angle, and orb.
The implementation exposes the core's product-relevant house systems
(placidus, whole_sign, equal) plus the registered engine systems, Mean
Node, Standard/Extended/Custom natal aspects, Mean/True Lilith, Vertex and Part
of Fortune requests, and named sidereal ayanamsas. The MCP contract does not
add calculation logic or interpretation. Composite and Davison are core/SDK
operations but are not MCP tools in this release.
Synastry accepts a relationship-level node_type so both charts use one node
convention, plus optional relationship_type, topic, and target_instant.
The server preserves response metadata and additive schema 1.x fields. A natal
HTTP response may omit calculationHash; that is valid and is never required.
The server preserves a returned v2: calculation hash without changing or
truncating it. Core compatibility is natal schema 1.9.0 and synastry schema
1.5.0.
getbirthchart://methodology — calculation conventions and unknown-time boundaries.getbirthchart://data-sources — ephemeris, timezone, and location-input provenance.getbirthchart://engine-info — provider and public API metadata.Authoritative web references: Methodology and Data Sources.
Tool failures use structured error data with a safe machine-readable code, message, retryable, and optional retry_after. Common codes include validation_error, authentication_required, birth_time_required, location_not_found, ambiguous_location, rate_limit_exceeded, timeout, and internal_error.
GETBIRTHCHART_API_KEY in the MCP host's server
environment; it is never a tool argument.code and
retry_after when present. Do not put the key in a tool call or client log.time when unknown_time is true; the
server will not substitute noon or invent a Rising sign.latitude, longitude, and
an IANA timezone; place is only a label and is not geocoded here.GETBIRTHCHART_API_BASE_URL only with HTTPS, or
HTTP on localhost. Never send a production key to an untrusted host.Birth data is passed only to the configured public API for the requested calculation. This package does not persist, cache, or log birth inputs, and it has no analytics or telemetry. The optional base URL override changes the trust boundary; do not send a production key to an untrusted host.
Report security issues privately through the process in SECURITY.md. Do not include API keys in bug reports.
Tests use mocked clients and do not call the production API. To run the built server locally, set GETBIRTHCHART_API_KEY and execute node dist/cli.js; normal protocol traffic stays on stdout, while startup failures are written to stderr.
Registry metadata is prepared in server.json with server name io.github.getbirthchart-com/getbirthchart-mcp. Publish the npm package first, then authenticate with the official mcp-publisher tool and publish the metadata. Registry submission is intentionally not part of the package build or CI workflow.