swiss-ephemeris

This MCP server provides astronomical calculations using the Swiss Ephemeris library. It exposes tools to compute planetary positions, house cusps using the Placidus system, chart points like Ascendant and Midheaven, and additional points such as the South Node and Part of Fortune. It also offers features for calculating birth chart transits, solar return charts, and synastry between two individuals. You can access these capabilities via the MCP API endpoints exposed by the server, enabling integration with astrology apps, horoscopes, or research pipelines. The server is designed to run locally or be exposed over HTTP when embedded in a web-accessible workflow, such as using Claude Desktop or a Docker deployment.

Prerequisites:

• Node.js (for local development) and npm/yarn
• Access to swetest for Claude Desktop integration as described below

Installation steps:

1. Install Swiss Ephemeris swetest (Claude Desktop usage):

   # Install swetest (required for Claude Desktop usage)
   git clone https://github.com/aloistr/swisseph.git /tmp/swisseph && \
       cd /tmp/swisseph && \
       make && \
       cp swetest /usr/local/bin/ && \
       rm -rf /tmp/swisseph
   

2. Install the MCP server (via GitHub npm package reference):

   git clone https://github.com/dm0lz/swiss-ephemeris-mcp-server.git
   cd swiss-ephemeris-mcp-server
   npm install
   npm start
   

3. Alternatively, use Claude Desktop integration (see Claude-specific config below).

Claude Desktop (optional) configuration:

{
  "mcpServers": {
    "swissEphemeris": {
      "command": "npx",
      "args": ["github:dm0lz/swiss-ephemeris-mcp-server"]
    }
  }
}

Docker (optional): Build and run if you prefer containerized deployment (see Docker notes in the README).

Tips and notes:

• The Swiss Ephemeris swetest binary is used for Claude Desktop integration. Ensure it is installed and accessible in your PATH when using Claude Desktop.
• If you expose the server over HTTP, you can set MCP_HTTP_MODE=true to enable web-based integration (ngrok or other tunneling can be used).
• The server supports multiple calculations: planetary positions, transits (birth chart vs current), solar return charts, and synastry between two charts. Each endpoint returns structured data including chart points and houses.
• For local development, using npx with the GitHub reference allows quick iteration without publishing a package.
• If you switch to Docker, follow the Docker instructions in the repository to set up port mappings and environment variables (e.g., MCP_HTTP_MODE).
• Health checks are available at /health when running with HTTP mode enabled.