Skip to content

README.md

Latest commit

 

History

History
131 lines (102 loc) · 3.73 KB

README.md

File metadata and controls

131 lines (102 loc) · 3.73 KB

AstroMCP

A Model Context Protocol (MCP) server providing astrological chart functionality for AI assistants.

npm version

🚀 Quick Start

  1. Clone the repository
  2. Install dependencies: 
    bun install
  3. Start the server: 
    bun run start

✨ Key Features

  • Generate detailed astrological charts based on date, time, and location
  • Seamless integration with AI assistants via Model Context Protocol
  • Powered by chart2txt for natural language chart interpretations
  • Uses Photon geocoding API for location lookups
  • Outputs planetary positions, house placements, and major aspects

📂 Project Structure

AstroMCP/
├── src/
│   ├── tools/
│   │   ├── getChart/        # Astrological chart functionality
│   │   └── ...              # Other tools
│   ├── utils/               # Shared utilities
│   ├── main.ts              # Server entry point
│   └── types.ts             # Shared type definitions
├── tests/                   # Test files
├── biome.json               # Linting configuration
├── tsconfig.json            # TypeScript configuration
└── package.json             # Project dependencies

🔮 Using the Astrology Tool

The get_chart tool accepts three parameters:

  • date: Date in YYYY-MM-DD format
  • time: Time in 24-hour format (HH:MM:SS)
  • location: Location in "city, country" format

Example response:

Astrology Chart (location: New York, USA, at: 1/1/2001, 1:01:00 AM):

Ascendant is at 21° Libra. Sun is at 10° Capricorn. Moon is at 21° Pisces. Mercury is at 14° Capricorn. Venus is at 27° Aquarius. Mars is at 5° Scorpio. Jupiter is at 2° Gemini. Saturn is at 24° Taurus. Uranus is at 18° Aquarius. Neptune is at 5° Aquarius. Pluto is at 13° Sagittarius.

Sun is in house 4. Moon is in house 6. Mercury is in house 4. Venus is in house 5. Mars is in house 2. Jupiter is in house 9. Saturn is in house 8. Uranus is in house 5. Neptune is in house 5. Pluto is in house 3.

Sun is in conjunction with Mercury (orb: 3.8°). Moon is in sextile with Saturn (orb: 2.8°). Venus is in square with Jupiter (orb: 4.9°). Venus is in square with Saturn (orb: 2.7°). Mars is in square with Neptune (orb: 0.3°). Jupiter is in trine with Neptune (orb: 3.2°).

⚙️ Configuration

API Endpoints

The server uses the following API endpoints:

  • Photon API (photon.komoot.io) for geocoding locations
  • Simple Astro API for planetary calculations (currently using hosted version)

Creating New Tools

The project includes a script to help create new MCP tools:

bun run scripts/create-tool.ts <tool-name>

🛠️ Development

  • Run tests: bun test
  • Format code: bun run format
  • Lint code: bun run lint
  • Build project: bun run build

To add your AstroMCP server to Claude Desktop:

  1. Build the project: 
    bun run build
  2. Add to your Claude Desktop config: 
    {
  "mcpServers": {
    "astrology-mcp-server": {
      "command": "/path/to/node",
      "args": ["/path/to/AstroMCP/dist/main.js"]
    }
  }
}

📦 Publishing to npm

  1. Ensure you're logged in to npm: 
    npm login
  2. Build the project: 
    bun run build
  3. Publish the package: 
    npm publish

Installing from npm (after publishing)

Add to your Claude Desktop config:

{
  "mcpServers": {
    "astro-server": {
      "command": "npx",
      "args": ["-y", "astrology-mcp-server"]
    }
  }
}