# Kundlit Vedic Astrology — MCP Server

[![Kundlit MCP server on Glama](https://glama.ai/mcp/servers/@puru991/kundlit-mcp/badge)](https://glama.ai/mcp/servers/@puru991/kundlit-mcp)

Free Vedic astrology computation for AI assistants over the
[Model Context Protocol](https://modelcontextprotocol.io): daily panchang and
muhurta timings for any city, janam kundali birth charts, kundli milan
(ashtakoot) matching, dosha checks, dasha periods, transits, festival and
eclipse calendars, and Vedic numerology — 17 tools (discovered dynamically),
plus prompts and documentation resources.

Results are deterministic — computed live with the Swiss Ephemeris on the
sidereal zodiac (Lahiri ayanamsa) — and backed by classical-text citations
on [kundlit.com](https://kundlit.com).

- **Server URL:** `https://kundlit.com/api/mcp` (hosted, Streamable HTTP)
- **Auth:** none — no account, no API key
- **Rate limit:** 30 requests/minute/IP
- **Docs:** https://kundlit.com/mcp
- **Privacy:** https://kundlit.com/privacy · **Support:** support@kundlit.com

## Install

### 1. `npx` (works with every client, including stdio-only ones)

```bash
npx -y @kundlit/mcp
```

That starts a local stdio MCP server which proxies to the hosted endpoint.
Point any client at it by command:

**Claude Desktop** — `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "kundlit-astro": {
      "command": "npx",
      "args": ["-y", "@kundlit/mcp"]
    }
  }
}
```

**Cursor** — `.cursor/mcp.json`, or any client that reads a generic
`.mcp.json`:

```json
{
  "mcpServers": {
    "kundlit-astro": {
      "command": "npx",
      "args": ["-y", "@kundlit/mcp"]
    }
  }
}
```

Installed globally (`npm i -g @kundlit/mcp`) the binary is `kundlit-mcp`, so
`"command": "kundlit-mcp"` with no args works too.

### 2. Direct Streamable HTTP (clients with remote-server support)

No bridge process needed — connect straight to the URL.

**Claude Code:**

```bash
claude mcp add --transport http kundlit https://kundlit.com/api/mcp
```

**Config file:**

```json
{
  "mcpServers": {
    "kundlit-astro": {
      "type": "http",
      "url": "https://kundlit.com/api/mcp"
    }
  }
}
```

**Claude (web/desktop):** Settings → Connectors → Add custom connector →
`https://kundlit.com/api/mcp`

Full per-client instructions, example prompts and limitations:
https://kundlit.com/mcp

## What is in this repository

The npm package `@kundlit/mcp` published from here is a **thin client**: a
bidirectional JSON-RPC pump between a local `StdioServerTransport` and a
`StreamableHTTPClientTransport` aimed at `https://kundlit.com/api/mcp`. It
contains no astrology logic and no copy of the tool list, so tools added or
renamed on the hosted server are picked up with no package update.

Frames are forwarded unmodified in both directions with one deliberate
exception: if the hop to the hosted server fails, the bridge answers the
pending request locally with a JSON-RPC `-32001` error (`bin/cli.js`) rather
than letting the local client hang forever on a reply that is never coming.
That error is synthesised by the bridge and was never sent by the server.

The astrology server itself is hosted at kundlit.com and its source is not
public. The manifests here (`.mcp.json`, `server.json`, `.claude-plugin/plugin.json`)
exist so MCP clients, registries and directories can discover and install it.

### Bridge options

```
kundlit-mcp [--url <endpoint>]

  --url <endpoint>   Hosted MCP endpoint (default https://kundlit.com/api/mcp).
                     Also settable via KUNDLIT_MCP_URL; --url wins.
  -h, --help         Usage and a config snippet.
  -v, --version      Package version.
```

stdout carries JSON-RPC and nothing else; all diagnostics, including `--help`
and `--version` output, go to stderr. Requires Node.js 18 or newer.

### Docker

```bash
docker build -t kundlit-mcp .
docker run -i --rm kundlit-mcp
```

The container speaks MCP over stdio, so run it with `-i` and no TTY.

### Development

```bash
npm install
node scripts/smoke.mjs   # end-to-end check against the live hosted server
```

## Capabilities

17 tools, discovered dynamically via `tools/list` — panchang, muhurta and
choghadiya windows, janam kundali, ashtakoot matching, manglik / kaal sarp /
sade sati checks, dasha periods, transits, pancha pakshi, year events,
eclipses, and numerology. Prompts and documentation resources
(`kundlit://docs/methodology`, `kundlit://docs/usage-guide`) are likewise
discovered at runtime; ask your client to list them rather than relying on a
list in this README.

## Example prompts

- "What is today's panchang in Jaipur? When is rahu kaal?"
- "Make a janam kundali for 14 March 1992, 6:45 am, Lucknow — which mahadasha am I running?"
- "Find me a good time tomorrow in Pune to sign a lease — avoid rahu kaal and bhadra."
- "All ekadashi dates in 2026 for Varanasi."

## Notes

- Free-text `place` (any city worldwide) is preferred; latitude/longitude/IANA
  timezone also accepted. Year tools snap to the nearest of 50 supported cities.
- Results are informational and not a substitute for professional advice.
- Every result carries a `Source:` attribution line — please keep it intact;
  that attribution is the price of free access.

## License

MIT — see [LICENSE](LICENSE).