Add Astrology to Your AI Agent with MCP

If you’ve worked with Claude Desktop in the last year, you’ve probably seen MCP — Model Context Protocol. It’s Anthropic’s open standard for connecting external tools to AI models. A few lines of config, and Claude can call your filesystem, your database, or any API.

This post shows how to add astrology calculations to an AI agent via MCP. Total time: under 5 minutes.

MCP is a protocol for AI models to call tools. Think of it as “REST APIs for AI agents”:

• A server exposes tools (calculations, queries, actions)
• A client (Claude Desktop, Cursor, custom agent) discovers and calls them
• The model decides when to use which tool based on user’s request

MCP servers can be local (run as a subprocess) or remote (HTTP). Most are local — published to npm and installed via npx.

AstroWay’s MCP server exposes 25 tools covering core astrology calculations:

• natal_chart — full natal chart
• synastry — two-person compatibility
• transits — current transits on natal
• daily_horoscope, weekly_horoscope, monthly_horoscope, yearly_horoscope
• interpret_natal, interpret_synastry, interpret_transits — AI interpretations
• human_design — full HD chart
• hd_incarnation_cross, hd_compatibility — HD features
• 12 more covering progressions, solar returns, astrocartography, rectification

Register at astroway.info and create a free API key (10,000 credits/month, no credit card).

Find claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the astroway server:

{
  "mcpServers": {
    "astroway": {
      "command": "npx",
      "args": ["@astroway/mcp"],
      "env": {
        "ASTROWAY_API_KEY": "aw_live_your_key_here"
      }
    }
  }
}

After restart, you’ll see a hammer icon showing 25 tools available.

Now just talk to Claude in natural language:

You: Build a natal chart for someone born July 14, 1990 at 14:30 in Kyiv. What does their Sun in Cancer in the 10th house mean?

Claude: Calls natal_chart with the parsed coordinates, then interpret_placement. Here’s the natal chart. Sun in Cancer in the 10th house suggests…

Claude handles:

• Parsing natural language (city → coordinates)
• Choosing the right tool
• Formatting the response

If you’re building a custom AI agent (not Claude Desktop), you can still use the MCP server. The protocol is documented:

import { spawn } from 'child_process';

const mcp = spawn('npx', ['@astroway/mcp'], {
  env: {
    ...process.env,
    ASTROWAY_API_KEY: process.env.ASTROWAY_API_KEY,
  },
  stdio: ['pipe', 'pipe', 'pipe'],
});

// Send MCP initialize message
mcp.stdin.write(JSON.stringify({
  jsonrpc: '2.0',
  id: 1,
  method: 'initialize',
  params: { protocolVersion: '2024-11-05', capabilities: {} },
}) + '\n');

// List tools
mcp.stdin.write(JSON.stringify({
  jsonrpc: '2.0',
  id: 2,
  method: 'tools/list',
}) + '\n');

// Call a tool
mcp.stdin.write(JSON.stringify({
  jsonrpc: '2.0',
  id: 3,
  method: 'tools/call',
  params: {
    name: 'natal_chart',
    arguments: {
      date: '1990-07-14',
      time: '14:30:00',
      timezoneOffset: 3,
      latitude: 50.4501,
      longitude: 30.5234,
    },
  },
}) + '\n');

Most agent frameworks (LangChain, LlamaIndex, etc.) have MCP support built-in.

If you don’t want MCP overhead, just call the HTTP API directly from your agent:

async function callAstrowayTool(tool: string, input: object) {
  const res = await fetch(`https://api.astroway.info/v1/${tool}`, {
    method: 'POST',
    headers: {
      'X-Api-Key': process.env.ASTROWAY_API_KEY!,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(input),
  });
  return res.json();
}

// Use in your agent loop
const chart = await callAstrowayTool('chart', birthData);

MCP advantages: structured tool definitions, auto-discovery, standardized error handling. HTTP advantages: simpler, works anywhere, no subprocess.

Once MCP is set up, try these with Claude:

1. “What’s my daily horoscope? I was born on October 3, 1993 at 6am in New York.”
2. “Calculate my Human Design type. Born April 22, 1987 at 16:45 in London.”
3. “Compare compatibility of two people: me (July 14 1990, Kyiv) and a friend (March 22 1992, Paris).”
4. “What are the major transits for me today? Give me an interpretation.”
5. “I don’t know my exact birth time. What does astrology sensitivity analysis say about a ±30 min range?”

Claude will pick appropriate tools, chain multiple calls when needed, and format human-readable output.

AstroWay’s AI interpretation tools (interpret_*, *_horoscope) have built-in safety guardrails:

• No medical, legal, or financial advice
• Auto-injected disclaimers
• Content filtering

When your agent surfaces interpretation text to users, preserve the disclaimer. It’s in the disclaimer field of every AI response.

MCP calls go through the same credit system as HTTP. Simple lookups (10 credits) → chart (20) → synastry (50) → AI interpretation (50).

For personal use (one user asking Claude questions), you’ll burn maybe 200–500 credits per month. Free tier covers it easily.

For a production agent serving hundreds of users, estimate based on the endpoint mix. A daily-horoscope bot for 1,000 users = 1,000 × 20 × 30 = 600,000 credits/month → Pro plan.

• AstroWay MCP on npm
• AI agents & MCP use case — full integration guide
• Horoscope & AI Interpretations API — product page
• Quick start — get your API key (free, 10,000 credits/mo)