{
  "markdown": "# @getbirthchart/mcp\n\nOfficial MCP server `0.2.0` for GetBirthChart astrology calculations. It gives\nMCP-compatible AI clients access to structured calculations through the public\nGetBirthChart API; it does not contain or reimplement the astrology engine.\n\n## Requirements\n\n- Node.js 20 or newer\n- A GetBirthChart developer API key\n\nCreate a key at [getbirthchart.com/developers](https://getbirthchart.com/developers). Keep it private and do not commit MCP host configuration containing the real key.\n\n## Quick start\n\nThe package runs over MCP stdio and can be launched with `npx`:\n\n```json\n{\n  \"mcpServers\": {\n    \"getbirthchart\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@getbirthchart/mcp@0.2.0\"],\n      \"env\": {\n        \"GETBIRTHCHART_API_KEY\": \"gbc_live_your_key_here\"\n      }\n    }\n  }\n}\n```\n\nThis 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.\n\n## Environment variables\n\n| Variable                     | Required | Description                                                                               |\n| ---------------------------- | -------- | ----------------------------------------------------------------------------------------- |\n| `GETBIRTHCHART_API_KEY`      | Yes      | Server-side developer API key.                                                            |\n| `GETBIRTHCHART_API_BASE_URL` | No       | HTTPS API base URL override for development/testing. HTTP is accepted only for localhost. |\n\nThe key is read at startup, never accepted as a tool argument, and never written to stdout, logs, resources, or tool results.\n\n## Available tools\n\nAll 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.\n\n| Tool                    | Input                                      | Output                         | Exact time required? | Unknown-time behavior                                         |\n| ----------------------- | ------------------------------------------ | ------------------------------ | -------------------- | ------------------------------------------------------------- |\n| `calculate_birth_chart` | `birthData`                                | Mapped natal chart              | No                   | Omits Ascendant and houses; preserves uncertainty.            |\n| `get_planet_positions`  | `birthData`                                | Planet placements               | No                   | Preserves chart uncertainty.                                  |\n| `get_big_three`         | `birthData`                                | Sun, Moon, and optional Rising  | No                   | Does not guess the Ascendant.                                 |\n| `get_moon_sign`         | `birthData`                                | Moon sign and uncertainty       | No                   | Returns ambiguity when the backend cannot establish one sign. |\n| `get_rising_sign`       | `birthData`                                | Rising sign                     | Yes                  | Returns `birth_time_required`.                                |\n| `calculate_aspects`     | `birthData`                                | Natal aspects                   | No                   | Returns backend-owned facts only.                             |\n| `calculate_synastry`    | `person_a`, `person_b`, relationship fields | Synastry aspects and summaries | Per person           | Preserves each person's unknown-time limits.                  |\n\nThe current public API does not geocode `place`; provide latitude, longitude,\nand an IANA timezone even when a place label is included. The MCP server never\ninvents a birth time. The backend may use local midnight as the labeled\ncalculation anchor for an unknown-time assessment, but it never presents that\nanchor as the person's birth time and never guesses houses, the Ascendant, or\nan ambiguous Moon sign.\n\nExample input:\n\n```json\n{\n  \"date\": \"1990-01-15\",\n  \"time\": \"12:00\",\n  \"place\": \"New York, NY\",\n  \"latitude\": 40.7128,\n  \"longitude\": -74.006,\n  \"timezone\": \"America/New_York\"\n}\n```\n\nUnknown time:\n\n```json\n{\n  \"date\": \"1990-01-15\",\n  \"unknown_time\": true,\n  \"latitude\": 40.7128,\n  \"longitude\": -74.006,\n  \"timezone\": \"America/New_York\"\n}\n```\n\n## Calculation options\n\nThe natal tools accept the exposed core `gbc-astro 1.13.0` options `house_system`,\n`node_type`, `aspect_preset`, `custom_aspect_rules`, `additional_points`,\n`fold`, `zodiac`, and `ayanamsa`. Omit them for the legacy-compatible defaults:\nTropical, Placidus, True Node, Standard aspects, Chiron on, and Lilith off.\nSidereal calculations require a named `ayanamsa`; Lahiri is the recommended\nproduct choice. Custom aspects require `custom_aspect_rules` and each rule uses\n`type`, `exact_angle`, and `orb`.\n\nThe implementation exposes the core's product-relevant house systems\n(`placidus`, `whole_sign`, `equal`) plus the registered engine systems, Mean\nNode, Standard/Extended/Custom natal aspects, Mean/True Lilith, Vertex and Part\nof Fortune requests, and named sidereal ayanamsas. The MCP contract does not\nadd calculation logic or interpretation. Composite and Davison are core/SDK\noperations but are not MCP tools in this release.\n\nSynastry accepts a relationship-level `node_type` so both charts use one node\nconvention, plus optional `relationship_type`, `topic`, and `target_instant`.\nThe server preserves response metadata and additive schema 1.x fields. A natal\nHTTP response may omit `calculationHash`; that is valid and is never required.\nThe server preserves a returned `v2:` calculation hash without changing or\ntruncating it. Core compatibility is natal schema `1.9.0` and synastry schema\n`1.5.0`.\n\n## Resources\n\n- `getbirthchart://methodology` — calculation conventions and unknown-time boundaries.\n- `getbirthchart://data-sources` — ephemeris, timezone, and location-input provenance.\n- `getbirthchart://engine-info` — provider and public API metadata.\n\nAuthoritative web references: [Methodology](https://getbirthchart.com/methodology/) and [Data Sources](https://getbirthchart.com/data-sources/).\n\n## Errors\n\nTool 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`.\n\n## Troubleshooting\n\n- **Missing API key:** set `GETBIRTHCHART_API_KEY` in the MCP host's server\n  environment; it is never a tool argument.\n- **Authentication or rate-limit errors:** use the structured error `code` and\n  `retry_after` when present. Do not put the key in a tool call or client log.\n- **Unknown-time validation:** omit `time` when `unknown_time` is `true`; the\n  server will not substitute noon or invent a Rising sign.\n- **Location validation:** include numeric WGS84 `latitude`, `longitude`, and\n  an IANA `timezone`; `place` is only a label and is not geocoded here.\n- **Local development:** use `GETBIRTHCHART_API_BASE_URL` only with HTTPS, or\n  HTTP on localhost. Never send a production key to an untrusted host.\n\n## Privacy and security\n\nBirth 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.\n\nReport security issues privately through the process in [SECURITY.md](./SECURITY.md). Do not include API keys in bug reports.\n\n## Development\n\n```bash\nnpm install\nnpm run lint\nnpm run typecheck\nnpm test\nnpm run build\n```\n\nTests 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.\n\n## Links\n\n- [Developer hub](https://getbirthchart.com/developers)\n- [GitHub repository](https://github.com/getbirthchart-com/getbirthchart-mcp)\n- [Core 1.13.0 GitHub release](https://github.com/getbirthchart-com/gbc-astro-engine/releases/tag/v1.13.0)\n- [Core 1.13.0 on PyPI](https://pypi.org/project/gbc-astro/1.13.0/)\n- [Core OpenAPI source](https://github.com/getbirthchart-com/gbc-astro-engine/blob/v1.13.0/src/gbc_astro/api/models.py)\n- [Concept DOI](https://doi.org/10.5281/zenodo.22052875) · [Version DOI](https://doi.org/10.5281/zenodo.22206006)\n- [npm package](https://www.npmjs.com/package/@getbirthchart/mcp)\n\n## MCP Registry metadata\n\nRegistry metadata is prepared in [`server.json`](./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.\n",
  "bytes": 9226,
  "sha": "7ef4ff1147c78833c0451cec7ce2a0783ea7fdce544eababdc9db2ffba8c3961",
  "repo_slug": "getbirthchart-com/getbirthchart-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_getbirthchart_com_getbirthchar_d6904084/readme"
}