MCP Server

The Morphemeris MCP server lets AI assistants call the Morphemeris API directly. Instead of copying and pasting data, you can ask your assistant questions like "What are the current planetary positions?" or "Calculate my natal chart" and it will fetch live data for you.

MCP (Model Context Protocol) is an open standard that lets AI applications use external tools. The Morphemeris MCP server provides 26 tools covering planetary positions, chart calculation, eclipses, returns, Arabic lots, and more.

What you need

1. A Morphemeris API key — sign up free (500 requests/month, no credit card required)
2. Node.js installed on your computer (download here — choose the LTS version)
3. An AI application that supports MCP

Node.js is required because the MCP server runs as a small local process on your computer. You only need to install it once.

Claude Desktop

Claude Desktop supports MCP servers through its configuration file.

Step 1: Find the config file

Open Claude Desktop, then go to Settings (gear icon) > Developer > Edit Config. This opens the configuration file in your text editor. If the file is empty, that's fine — you'll add to it in the next step.

On macOS, the file is at: ~/Library/Application Support/Claude/claude_desktop_config.json

On Windows, the file is at: %APPDATA%\Claude\claude_desktop_config.json

Step 2: Add the Morphemeris server

Replace the file contents with the following (or merge it into your existing configuration if you already have other MCP servers):

{
  "mcpServers": {
    "morphemeris": {
      "command": "npx",
      "args": ["-y", "@morphemeris/mcp"],
      "env": {
        "MORPHEMERIS_API_KEY": "morphemeris_live_YOUR_KEY_HERE"
      }
    }
  }
}

Replace morphemeris_live_YOUR_KEY_HERE with your actual API key from your dashboard.

Step 3: Restart Claude Desktop

Quit Claude Desktop completely and reopen it. You should see a hammer icon in the chat input area — click it to verify that Morphemeris tools are listed.

ChatGPT Desktop

ChatGPT Desktop supports MCP servers on macOS and Windows.

Step 1: Open MCP settings

Go to Settings > Tools & Plugins > Add MCP Server.

Step 2: Add the server

• Name: Morphemeris
• Command: npx
• Arguments: -y @morphemeris/mcp
• Environment variables: Add MORPHEMERIS_API_KEY with your API key as the value

Step 3: Enable the server

After adding, make sure the Morphemeris server is toggled on. ChatGPT will start the server automatically when you begin a conversation.

Msty

Msty is a desktop AI chat app (Mac, Windows, Linux) that connects to multiple LLM providers and supports MCP servers.

Go to Settings > MCP Servers > Add Server and enter the following JSON configuration:

{
  "morphemeris": {
    "command": "npx",
    "args": ["-y", "@morphemeris/mcp"],
    "env": {
      "MORPHEMERIS_API_KEY": "morphemeris_live_YOUR_KEY_HERE"
    }
  }
}

Replace morphemeris_live_YOUR_KEY_HERE with your actual API key, save, and restart Msty.

Other MCP-compatible apps

Many AI chat applications use the same JSON configuration format for MCP servers. If your app supports MCP and asks for a server config, use this:

{
  "command": "npx",
  "args": ["-y", "@morphemeris/mcp"],
  "env": {
    "MORPHEMERIS_API_KEY": "morphemeris_live_YOUR_KEY_HERE"
  }
}

This works with apps like Cherry Studio, TypingMind, Jan, and others. Check your app's documentation for where to add MCP server configurations.

What you can ask

Once the MCP server is connected, you can ask your AI assistant questions in natural language. Here are some examples:

Planetary positions and charts

• "What are the current planetary positions?"
• "Calculate a natal chart for June 15, 1990 at 2:30 PM in New York"
• "What sign is the Moon in right now?"

Relationships and compatibility

• "Compare my chart (June 15 1990, 2:30 PM, New York) with my partner's (March 22 1988, 10 AM, London)"
• "Calculate our composite chart"

Timing and planning

• "When is the next solar eclipse?"
• "Is the Moon void of course right now?"
• "What planetary hour is it in New York?"
• "Is Mercury combust right now?"

Returns and forecasts

• "Calculate my 2025 solar return for Harrisonburg, VA"
• "When is my next lunar return?"
• "What's my Part of Fortune?"

Progressions and derived charts

• "What are my current secondary progressions?"
• "Show my draconic chart"

The assistant will automatically choose the right Morphemeris tool and format the results for you. You don't need to know endpoint names or parameters — just describe what you want.

A note about times and locations

The Morphemeris API works in UTC (Coordinated Universal Time). When you mention a local time like "2:30 PM Eastern," your AI assistant converts it to UTC automatically. This is usually correct, but for historical dates — especially before 2000 or in regions with unusual daylight saving time changes — you may want to provide the UTC time directly for maximum accuracy.

For location, you can use city names (your assistant will look up the coordinates) or provide latitude and longitude directly for precision.

For developers

If you're integrating the MCP server into a coding agent (Claude Code, Cursor, VS Code Copilot, Windsurf, Codex, Gemini CLI), see the detailed setup instructions in the @morphemeris/mcp package documentation.

Pricing

The MCP server uses your Morphemeris API key, so standard pricing applies. The free tier includes 500 requests/month — more than enough for casual use. Each tool call costs 1-3 credits depending on the computation.