Using MCP for Astrology: Claude + Cursor Integration Guide

The Model Context Protocol (MCP) lets AI assistants like Claude and Cursor call external tools directly. With the GitStrology MCP server, you can ask your AI assistant to pull natal charts, daily horoscopes, compatibility reports, and tarot readings without ever leaving your editor. This guide walks through setup for both Claude Desktop and Cursor.

What Is MCP?

The Model Context Protocol is an open standard that allows AI assistants to interact with external APIs and tools through a standardized interface. Instead of copy-pasting API responses into a chat window, the assistant calls the tool directly and receives structured data it can reason about. This transforms astrology APIs from something you integrate into code into something you can converse with.

GitStrology is the first astrology API to ship an MCP server. This means you can ask Claude or Cursor to generate a natal chart, interpret a transit, or compare compatibility between two people — and the assistant fetches real astrological data through the GitStrology API to ground its response.

Why Use GitStrology with MCP?

Traditional astrology workflows involve looking up ephemeris tables, switching to a chart calculator website, and manually copying data into your notes or code. With MCP, the entire workflow stays inside your AI assistant. You describe what you want in natural language, and the assistant calls the appropriate GitStrology endpoint, receives structured JSON, and interprets it for you.

This is particularly powerful for developers building astrology applications. You can prototype features by asking the assistant to fetch sample data, test different birth charts, and even write integration code that uses the GitStrology SDK — all within a single conversation.

Available MCP Tools

The GitStrology MCP server exposes eight tools, each mapping to a GitStrology API endpoint:

Each tool accepts the same parameters as the corresponding REST endpoint. The MCP server handles authentication, request formatting, and response parsing automatically. Credit costs match the standard API — see rate limits and credits for details.

Prerequisites

• A GitStrology API key (free tier works fine — get one here)
• Claude Desktop or Cursor installed on your machine
• Node.js 18 or later (for running the MCP server)

Installing the MCP Server

The GitStrology MCP server runs as an npx process — no global installation required. Your AI assistant launches it automatically when configured. You just need Node.js available on your system and your API key ready.

To verify the server runs correctly before configuring your assistant, test it from the terminal:

GITSTROLOGY_API_KEY=gs_live_xxxxx npx @gitstrology/mcp-server

If the server starts without errors, it is ready to be connected to your AI assistant. Kill the process with Ctrl+C — your assistant will manage the lifecycle.

Configuring Claude Desktop

Claude Desktop uses a JSON configuration file to register MCP servers. The file is located at:

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

Open (or create) the file and add the GitStrology server under the mcpServers key:

{
  "mcpServers": {
    "gitstrology": {
      "command": "npx",
      "args": ["@gitstrology/mcp-server"],
      "env": {
        "GITSTROLOGY_API_KEY": "gs_live_your_key_here"
      }
    }
  }
}

After saving the file, restart Claude Desktop. The GitStrology tools will now be available. Claude automatically detects when a question requires astrological data and calls the appropriate tool. You can verify the connection by asking Claude something like:

"What's today's horoscope for Scorpio?"

Claude will call the horoscope tool with { sign: "scorpio" } and return the reading with mood, energy ratings, and advice.

Configuring Cursor

Cursor supports MCP servers through its settings configuration. Create or edit the MCP configuration file at .cursor/mcp.json in your project root (or in your home directory for global access):

{
  "mcpServers": {
    "gitstrology": {
      "command": "npx",
      "args": ["@gitstrology/mcp-server"],
      "env": {
        "GITSTROLOGY_API_KEY": "gs_live_your_key_here"
      }
    }
  }
}

After saving, restart Cursor or reload the window. The GitStrology tools will appear in Cursor's available tools list. You can now ask Cursor's AI assistant to fetch astrological data while you write code, build features, or debug your application.

Example Prompts to Try

Once your MCP server is configured, here are prompts that demonstrate the range of what you can do. These work in both Claude Desktop and Cursor:

Daily Horoscopes

"What's the horoscope for Gemini today?"
"Give me horoscopes for all fire signs (aries, leo, sagittarius)."
"What's today's lucky number and color for Virgo?"

Natal Chart Analysis

"Generate a natal chart for someone born March 15, 1990 at 2:30 PM in Belgrade (lat 44.8, lon 20.4)."
"What does it mean that my sun is in Pisces and my moon is in Leo?"
"Which planets are retrograde in this chart?"

Compatibility Reports

"Compare compatibility between someone born March 15, 1990 at 2:30 PM in Belgrade and someone born July 22, 1988 at 9:00 AM in New York."
"Are a Pisces sun and Cancer sun compatible? Pull the actual synastry data."

Transits and Predictions

"What planetary transits are active right now for someone born on March 15, 1990?"
"Is Saturn currently transiting my natal sun? Check the transit data."

Tarot and Numerology

"Pull a three-card tarot spread for me."
"What's the numerological significance of the name 'Alexander' born on January 5, 1992?"

Moon Phases

"What phase is the moon in right now?"
"What's the moon phase and zodiac sign for August 15, 2026?"

Development Workflows

"Fetch a sample natal chart response so I can write TypeScript types for it."
"Generate a daily horoscope for Aries and write a React component to display it."
"Write a Next.js API route that calls the GitStrology natal chart endpoint."

How Credit Usage Works with MCP

Every tool call through the MCP server consumes the same credits as a direct API call. The free tier includes 100 credits per month. Here is how that budget maps to common MCP workflows:

Free tier: 100 credits/month

  100 horoscope calls (1 credit each)
  OR 50 numerology + tarot calls (2 credits each)
  OR 33 tarot readings (3 credits each)
  OR 20 natal charts (5 credits each)
  OR 20 compatibility reports (5 credits each)
  OR 20 transit reports (5 credits each)

If you use MCP heavily for development and testing, consider upgrading to the Pro plan for 10,000 monthly credits. This gives you ample room for prototyping, building, and running automated workflows without worrying about running out.

Combining MCP with the SDK

MCP and the SDK are complementary tools. Use MCP when you want to explore data, prototype ideas, or have a conversation about astrological concepts. Use the SDK when you are writing production code that needs to call the API programmatically. Here is a typical workflow:

1. Ask Claude via MCP to fetch a sample natal chart response so you understand the data structure.
2. Ask Claude to generate TypeScript interfaces based on the response.
3. Write your application code using the GitStrology SDK, referencing the types and sample data.
4. Ask Cursor to help you build React components that render the chart data, using real API responses as examples.

Security Best Practices

• Never commit your API key in the MCP config file if it lives in a repository. Use a .gitignore entry for .cursor/mcp.json.
• For Claude Desktop, the config file lives outside your project directory and is not committed to git by default.
• Use a dedicated API key for MCP usage so you can revoke it independently of your production key if needed.
• Monitor your credit usage. The MCP server makes it easy to fire off many requests in rapid succession during a conversation. See rate limits for per-minute caps.

Troubleshooting

The assistant does not recognize GitStrology tools

Make sure you restarted Claude Desktop or Cursor after editing the config file. Check that the JSON is valid — a syntax error will silently prevent the server from loading. Verify your Node.js version is 18 or later:

node --version

Tool calls return authentication errors

Verify that your API key is correct and starts with gs_live_. Keys are managed in the dashboard. If you see a 401 or auth_failed error, regenerate the key and update your MCP config. See the authentication docs for details.

Tool calls fail with credit errors

If you see a 402 error or a message about insufficient credits, you have exhausted your monthly allocation. Check your remaining credits on the dashboard or upgrade to the Pro plan.

Key Takeaways

• The GitStrology MCP server lets Claude Desktop and Cursor call astrology endpoints directly through natural language.
• Eight tools are available: natal_chart, horoscope, compatibility, transits, tarot, numerology, moon_phase, and sun_sign.
• Configuration is a single JSON block in claude_desktop_config.json (Claude) or .cursor/mcp.json (Cursor).
• Credit costs match the REST API. The free tier's 100 credits cover plenty of experimentation.
• MCP is complementary to the SDK — use MCP for exploration and prototyping, the SDK for production code.
• Use a dedicated API key for MCP and never commit keys to version control.

Ready to bring astrology into your AI workflow? Get your API key from the dashboard, follow the quickstart guide to verify it works, and configure your MCP server in minutes.