Vedic Birth Chart MCP Server

An MCP (Model Context Protocol) tool that AI agents can call to fetch a Vedic D1 (Rasi) birth chart from a date of birth, time of birth, and birthplace coordinates, via FreeAstrologyAPI's /planets endpoint.

What it does

The tool get_d1_birth_chart takes year, month, day, hour, minute, second, latitude, longitude, timezone (plus optional observationPoint and ayanamsha), calls POST https://json.freeastrologyapi.com/planets with the matching payload, and returns the API's D1 chart response (planetary positions) as-is.

Field mapping to the API (handled internally, so the agent only needs the friendly names):

Tool input	API field
day	date
hour	hours
minute	minutes
second	seconds
observationPoint	config.observation_point (default topocentric)
ayanamsha	config.ayanamsha (default lahiri)

year, month, latitude, longitude, timezone are passed straight through.

Setup

Requires Node.js 18+.

cd vedic-birth-chart-mcp
npm install
npm run build

API key

Set your FreeAstrologyAPI key in a .env file at the project root (already gitignored):

FREEASTROLOGY_API_KEY=your-api-key-here

A .env with the key you provided is already in place. .env.example shows the expected format. You can also set FREEASTROLOGY_API_KEY as a real environment variable instead (e.g. in your MCP client's server config), which takes precedence over .env.

Try it standalone (no MCP client needed)

npm run test

This calls the live API with the same example as FreeAstrologyAPI's own /planets docs (10 Feb 1991, 21:35, Bikaner) and prints the raw JSON response.

Add it to an MCP-compatible agent

Claude Desktop / Claude Code — add to your MCP config (e.g. claude_desktop_config.json or .mcp.json):

{
  "mcpServers": {
    "vedic-birth-chart": {
      "command": "node",
      "args": ["/absolute/path/to/vedic-birth-chart-mcp/dist/server.js"],
      "env": {
        "FREEASTROLOGY_API_KEY": "your-api-key-here"
      }
    }
  }
}

Restart the client. The agent will then see a tool named get_d1_birth_chart it can call directly — e.g. "What's the D1 chart for someone born 10 Feb 1991, 21:35, at 28.027, 73.302, UTC+5:30?"

Project structure

src/
  config.ts            Loads FREEASTROLOGY_API_KEY via dotenv (from .env or real env var)
  freeAstrologyApi.ts   Calls FreeAstrologyAPI's /planets endpoint, maps friendly field names
  server.ts             MCP server exposing get_d1_birth_chart
  test.ts               Standalone example run against the live API

Notes

• Verified in this environment: the request payload sent to the API was checked against a local mock server and exactly matches the field names/shape from FreeAstrologyAPI's own curl example (date/hours/minutes/seconds, nested config.observation_point / config.ayanamsha). The build compiles cleanly against the real @modelcontextprotocol/sdk types. The live API call itself could not be exercised end-to-end here because this sandbox has no outbound network access — run npm run test on your own machine to confirm the live response shape.
• The tool currently passes through FreeAstrologyAPI's response unmodified rather than reshaping it, since the exact response schema wasn't verifiable without live network access. If you'd like it parsed into a friendlier structure (e.g. named sign/house per planet), run npm run test once, share the output, and that mapping can be added.
• API usage is subject to FreeAstrologyAPI's own rate limits/quota on your key.
• .env loading uses the dotenv npm package. That means you need to run npm install again to pull it in before building — this sandbox has no npm registry access, so the new dependency couldn't be installed or type-checked here. npx tsc --noEmit on your machine will confirm it compiles.