GetBirthChart MCP

@getbirthchart/mcp

Official MCP server 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.

Requirements

• Node.js 20 or newer
• A GetBirthChart developer API key

Create a key at getbirthchart.com/developers. Keep it private and do not commit MCP host configuration containing the real key.

Quick start

The package runs over MCP stdio and can be launched with npx:

{
  "mcpServers": {
    "getbirthchart": {
      "command": "npx",
      "args": ["-y", "@getbirthchart/mcp"],
      "env": {
        "GETBIRTHCHART_API_KEY": "gbc_live_your_key_here"
      }
    }
  }
}

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.

Environment variables

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.

Available tools

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.

Tool	Purpose	Exact time required?	Unknown-time behavior
calculate_birth_chart	Full natal chart facts	No	Omits Ascendant and houses; preserves uncertainty.
get_planet_positions	Planetary placements	No	Preserves chart uncertainty.
get_big_three	Sun, Moon, and Ascendant	No	Does not guess the Ascendant.
get_moon_sign	Moon sign and certainty	No	Returns ambiguity when the backend cannot establish one sign.
get_rising_sign	Ascendant	Yes	Returns birth_time_required.
calculate_aspects	Natal aspects	No	Returns backend-owned facts only.
calculate_synastry	Inter-chart relationships for person_a and person_b	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 assumes noon or midnight and never guesses houses, the Ascendant, or an ambiguous Moon sign.

Example input:

{
  "date": "1990-01-15",
  "time": "12:00",
  "place": "New York, NY",
  "latitude": 40.7128,
  "longitude": -74.006,
  "timezone": "America/New_York"
}

Unknown time:

{
  "date": "1990-01-15",
  "unknown_time": true,
  "latitude": 40.7128,
  "longitude": -74.006,
  "timezone": "America/New_York"
}

Resources

• 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.

Errors

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.

Privacy and security

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.

Development

npm install
npm run lint
npm run typecheck
npm test
npm run build

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.

Links

• Developer hub
• GitHub repository
• npm package

MCP Registry metadata

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.