astrology-mcp

Install once, share birth details once, then ask ordinary questions.

astrology-mcp is a local Model Context Protocol server for Indian astrology (Jyotisha). It gives agents deterministic Lahiri sidereal calculations, question-aware natal context, Vimshottari dasha, and current gochara instead of a context-free horoscope.

The human speaks naturally. The agent resolves their birthplace, determines the historical timezone, stores a private local profile, and reuses it for future conversations across MCP clients. Calculated evidence is separated from tradition-dependent interpretation through a bundled agent reference guide.

Astrology is an interpretive tradition, not a scientifically validated predictive method. This server makes the calculation and evidence trail reproducible; it does not make predictions certain.

What it calculates

• Swiss Ephemeris geocentric graha longitudes, with the Moshier analytical ephemeris as the no-data-file fallback
• Lahiri/Chitrapaksha sidereal zodiac
• Whole-sign houses from the sidereal ascendant
• Sun, Moon, Mars, Mercury, Jupiter, Venus, Saturn, true Rahu, and opposite Ketu
• Nakshatra, pada, sign dignity, motion, and D9 Navamsha placement
• Tithi, karana, nakshatra, yoga, and civil vara at the requested instant
• Vimshottari mahadasha, antardasha, pratyantardasha, birth balance, and period timeline
• Current placements from natal lagna and Moon, full sign-based Parashari graha drishti, and Sade Sati geometry
• A topic filter for career, relationships, finance, health, education, family/home, spirituality, or general questions
• Purpose-limited, free birth/current-place lookup through Nominatim/OpenStreetMap when coordinates are unknown

Calculation conventions and deliberate exclusions are documented in the MCP resource astrology://reference/guide.

Requirements

• Python 3.11 or newer
• uv for the commands below, or another Python package installer

Install once, then talk normally

Install the executable once on the machine:

uv tool install .
astrology-mcp --version

When distributed through a package index, the corresponding command is:

uv tool install astrology-mcp

Register that executable once in any stdio-capable MCP client. Generate the generic configuration:

astrology-mcp --print-config

It prints:

{
  "mcpServers": {
    "astrology": {
      "command": "astrology-mcp",
      "args": []
    }
  }
}

Claude Desktop, Cursor, VS Code integrations, Codex-compatible clients, and other stdio MCP hosts use this same command even when their settings file or UI differs. MCP clients do not share a global server registry, so each host must be pointed at the executable once. The installed server and saved profiles are machine-wide for the user; birth details do not need to be re-entered in each client.

After registration, the human only talks:

Human: I was born on 22 January 2000 at 9:30 PM in Jayanagar, Bangalore.
Agent:  [resolves the place, calculates the historical timezone, and saves profile “me”]

Human: What should I pay attention to in my career this year?
Agent:  [calls ask_astrology using the saved profile and current time]

The human never needs to write JSON, find coordinates, calculate a UTC offset, name an MCP tool, or paste birth details again.

For development without a persistent install:

uv sync
uv run astrology-mcp

The default transport is stdio. Streamable HTTP remains available for managed deployments:

ASTROLOGY_MCP_HOST=127.0.0.1 ASTROLOGY_MCP_PORT=8000 \
  astrology-mcp --transport streamable-http

Agent contract

MCP clients receive these instructions from the server automatically. An integrating agent should follow the same contract:

1. Start a personal conversation with list_birth_profiles.
2. If the intended profile exists, call ask_astrology with the human's question. Never ask them to repeat saved birth details.
3. If it does not exist, ask only for birth date, exact local clock time, and ordinary birthplace. The human should not need coordinates, timezone syntax, JSON, or MCP vocabulary.
4. Resolve the place with resolve_birth_location; verify the returned address and ask only when candidates are genuinely ambiguous.
5. Save with save_birth_profile. Historical timezone and UTC offset resolution happen offline.
6. Read astrology://reference/guide, then interpret the structured context returned by ask_astrology.
7. Separate calculated facts from interpretation, state conflicting evidence and uncertainty, and never substitute astrology for medical, legal, financial, or safety-critical judgment.

Use get_person_context and calculate_chart only for advanced stateless integrations. Delete saved data only after an explicit human request.

MCP interface

Normal conversational flow

The server instructions teach any MCP-capable agent this sequence:

1. list_birth_profiles checks whether the person has already been onboarded.
2. resolve_birth_location converts their ordinary birthplace description into candidates. The agent verifies the address and asks only if the result is genuinely ambiguous.
3. save_birth_profile accepts a normal calendar date, local clock time, and confirmed coordinates. It resolves the IANA timezone and historical UTC offset offline, then persists the profile locally.
4. ask_astrology needs only the question and profile name. It loads birth data and uses the current instant automatically.
5. delete_birth_profile runs only when the human explicitly asks the agent to forget a profile.

me is the default profile. Other names allow explicitly requested profiles such as partner, without mixing charts.

Free place lookup

resolve_birth_location uses the public OpenStreetMap Nominatim service by default. It returns full display names and address components; it never silently decides between ambiguous places. The server identifies itself, serializes requests to one per second, caches 256 queries in memory, returns attribution, and links the Nominatim usage policy. It is not an autocomplete or bulk-geocoding endpoint.

Override it for private or higher-volume operation:

export ASTROLOGY_MCP_GEOCODER_URL="https://nominatim.example.com/search"
export ASTROLOGY_MCP_GEOCODER_USER_AGENT="your-application/1.0 contact@example.com"
export ASTROLOGY_MCP_GEOCODER_EMAIL="contact@example.com"

Offline timezone handling

timezonefinder maps the confirmed coordinates to an IANA timezone without sending birth data to a service. Python's zoneinfo and bundled tzdata determine the offset that applied on the birth date. Nonexistent daylight-saving times are rejected. Repeated clock times require the agent to ask whether the birth occurred during the first or second occurrence.

Advanced/stateless tools

• get_person_context accepts complete offset-aware birth data directly for programmatic callers that manage their own profiles.
• calculate_chart computes one standalone Rashi/D9 chart and panchanga.

Ordinary agents should use ask_astrology after onboarding rather than repeatedly calling these tools.

Resource and prompt

• astrology://reference/guide contains the calculation contract, synthesis hierarchy, interpretive reference, data-quality rules, and answer protocol.
• personal_jyotisha_reading handles either first-time conversational onboarding or an existing saved profile.

Data rules

For saved profiles, the human supplies only a calendar birth date, exact local clock time, and ordinary birthplace description. Timezone and historical offset resolution happen locally after the place is confirmed. Advanced stateless calls still require an explicit offset-aware timestamp.

Profiles are stored in the user's platform data directory as astrology-mcp/profiles.json, with owner-only permissions where supported. Set ASTROLOGY_MCP_DATA_DIR to choose another local directory. Profiles contain birth data; questions and calculated readings are never persisted. Every client using the same operating-system account sees the same profiles.

Chart, dasha, and timezone calculations run locally. resolve_birth_location sends only its place query to the configured geocoder and caches the result in process memory; do not include a person's name, exact private residential address, or confidential information. No chart, timestamp, question, or saved profile is sent.

If SE_EPHE_PATH points to Swiss Ephemeris data files, they are used; otherwise each result transparently reports the Moshier analytical fallback.

Scope and safety

Jyotisha is an interpretive tradition, not a scientifically validated predictive method. Results should be phrased as symbolic tendencies and timing windows, never certainties. The reference prompt prohibits deterministic claims and prohibits substituting astrology for medical, legal, financial, or safety-critical judgment.

The server does not claim to calculate Shadbala, Ashtakavarga, all named yogas, bhava cusps, rectification, sunrise-based vara, a full varga suite, or muhurta. Agents must not invent those factors.

Dependency licensing

pyswisseph declares the GNU Affero General Public License v3 in its package metadata. Swiss Ephemeris is also offered under a commercial professional license. Review those terms before distributing this server or using it in a networked commercial product; this repository does not grant a separate Swiss Ephemeris license.

Verification

Run the calculation and MCP protocol tests:

uv run python -m unittest discover -s tests -v

Build the installable wheel:

uv build