# 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](https://freeastrologyapi.com)'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+.

```bash
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)

```bash
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`):

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