GetBirthChart MCP

io.github.getbirthchart-comPublished by GitHub account getbirthchart-comv0.1.1Updated Oct 24, 2026

Official MCP server for GetBirthChart astrology calculations.

VerifiedSTDIODesktop onlyLocation & LifestyleData & Analytics

Overview

AI-generated overview

Official GetBirthChart MCP server that lets an assistant compute natal charts, planet positions, signs, aspects and synastry via the GetBirthChart API.

What you can do
  • Calculate a full natal chart, planet positions, aspects, and the Sun/Moon/Rising "big three" from birth data
  • Look up a Moon sign or Rising sign, with explicit uncertainty when the birth time is unknown
  • Compute synastry aspects and summaries between two people's charts
  • Apply calculation options such as house system, node type, aspect presets, zodiac and ayanamsa
  • Read reference resources on methodology, data sources and engine info
When to use it
Useful when you want an assistant to produce structured astrology calculations from birth date, time and coordinates, including charts for people with unknown birth times, without building the astrology engine yourself.
Requirements
Runs locally over stdio via npx, so Node.js 20 or newer is needed. A GetBirthChart developer API key must be supplied in the GETBIRTHCHART_API_KEY environment variable. Network access to the GetBirthChart public API is required; an optional GETBIRTHCHART_API_BASE_URL override exists for development. Inputs need numeric latitude, longitude and an IANA timezone, since place names are not geocoded.
Before you install
The API key is a secret read at startup; keep it out of tool calls, logs and committed host configuration. Birth data, including date, time and coordinates, is sent to the GetBirthChart public API for each calculation. Changing the base URL override moves the trust boundary, so do not send a production key to an untrusted host. Tools are read-only and the package states it does not persist or log birth inputs.

Installation

In SourceWeft

  1. Open GetBirthChart MCP in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

@getbirthchart/mcp

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.

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:

json
{  "mcpServers": {    "getbirthchart": {      "command": "npx",      "args": ["-y", "@getbirthchart/[email protected]"],      "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

VariableRequiredDescription
GETBIRTHCHART_API_KEYYesServer-side developer API key.
GETBIRTHCHART_API_BASE_URLNoHTTPS 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 and calculation settings documented below.

ToolInputOutputExact time required?Unknown-time behavior
calculate_birth_chartbirthDataMapped natal chartNoOmits Ascendant and houses; preserves uncertainty.
get_planet_positionsbirthDataPlanet placementsNoPreserves chart uncertainty.
get_big_threebirthDataSun, Moon, and optional RisingNoDoes not guess the Ascendant.
get_moon_signbirthDataMoon sign and uncertaintyNoReturns ambiguity when the backend cannot establish one sign.
get_rising_signbirthDataRising signYesReturns birth_time_required.
calculate_aspectsbirthDataNatal aspectsNoReturns backend-owned facts only.
calculate_synastryperson_a, person_b, relationship fieldsSynastry aspects and summariesPer personPreserves 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:

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

Unknown time:

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

Calculation options

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.

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.

Troubleshooting

  • Missing API key: set GETBIRTHCHART_API_KEY in the MCP host's server environment; it is never a tool argument.
  • Authentication or rate-limit errors: use the structured error code and retry_after when present. Do not put the key in a tool call or client log.
  • Unknown-time validation: omit time when unknown_time is true; the server will not substitute noon or invent a Rising sign.
  • Location validation: include numeric WGS84 latitude, longitude, and an IANA timezone; place is only a label and is not geocoded here.
  • Local development: use GETBIRTHCHART_API_BASE_URL only with HTTPS, or HTTP on localhost. Never send a production key to an untrusted host.

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

bash
npm installnpm run lintnpm run typechecknpm testnpm 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

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.

Source: README.md at commit c8c93dd

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.1.1LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts