@guanxing/mcp-server

MCP server for 观星 (GuanXing) — AI-powered Chinese metaphysics tools for LLM assistants.

Give your AI assistant access to BaZi (八字), Tarot, I-Ching divination (求签), Feng Shui, dream interpretation, Chinese almanac, and more — all through the Model Context Protocol.

What is 观星 (GuanXing)?

GuanXing is an AI-powered Chinese metaphysics platform that combines thousands of years of Eastern wisdom with modern AI. It provides accurate, personalized readings across multiple metaphysics disciplines — from Four Pillars destiny analysis to tarot card readings.

This MCP server connects your AI assistant (Claude, GPT, etc.) directly to GuanXing's API, so you can ask questions like:

• "What does my BaZi chart say about my career?"
• "Draw me a tarot spread for my relationship question"
• "Is today auspicious for signing a contract?"
• "Analyze the feng shui of my home office facing south"

Available Tools

| Tool | Description | |------|-------------| | bazi_analysis | Analyze Chinese Four Pillars (八字) based on birth date and time. Returns heavenly stems, earthly branches, five elements, and day master analysis. | | daily_fortune | Personalized daily fortune by zodiac sign. Scores for career, love, wealth, health, plus lucky color and number. | | qiuqian | Draw a divine lot (求签) — traditional temple fortune stick divination with poem and interpretation. Choose Guanyin or Guandi style. | | almanac | Chinese almanac (黄历) lookup. Lunar date, auspicious/inauspicious activities, hourly fortune, and daily summary. | | dream_interpret | Dream interpretation combining Zhou Gong (周公解梦) tradition with modern psychology. Symbols, meaning, and advice. | | tarot | Tarot card reading with single-card, three-card, or Celtic cross spreads. Full card meanings and comprehensive interpretation. | | name_score | Chinese name scoring using Five Grid numerology (五格剖象法). Total score, grid breakdown, and five elements analysis. | | fengshui | Feng shui assessment for home, office, or shop. Score, suggestions, lucky items, and things to avoid. | | compatibility | Compatibility analysis between two people based on birth info, zodiac, or names. Multi-dimensional scoring. | | zodiac | In-depth zodiac sign analysis — personality traits, element, ruling planet, and sign compatibility. | | community_browse | Browse the latest community posts on GuanXing. | | community_post | Create a new post in the GuanXing community. |

Quick Start

1. Get an API Key

Register at heartai.zeabur.app and create an API key in your developer settings.

2. Configure Your MCP Client

Add the server to your MCP client configuration:

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "guanxing": {
      "command": "npx",
      "args": ["-y", "@guanxing/mcp-server"],
      "env": {
        "GUANXING_API_KEY": "your-api-key-here"
      }
    }
  }
}

Claude Code (CLI)

Edit ~/.claude/settings.json or .mcp.json in your project:

{
  "mcpServers": {
    "guanxing": {
      "command": "npx",
      "args": ["-y", "@guanxing/mcp-server"],
      "env": {
        "GUANXING_API_KEY": "your-api-key-here"
      }
    }
  }
}

Cursor

Open Settings > MCP and add:

{
  "guanxing": {
    "command": "npx",
    "args": ["-y", "@guanxing/mcp-server"],
    "env": {
      "GUANXING_API_KEY": "your-api-key-here"
    }
  }
}

Cline (VS Code)

Edit your Cline MCP settings:

{
  "mcpServers": {
    "guanxing": {
      "command": "npx",
      "args": ["-y", "@guanxing/mcp-server"],
      "env": {
        "GUANXING_API_KEY": "your-api-key-here"
      }
    }
  }
}

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "guanxing": {
      "command": "npx",
      "args": ["-y", "@guanxing/mcp-server"],
      "env": {
        "GUANXING_API_KEY": "your-api-key-here"
      }
    }
  }
}

3. Start Using It

Once configured, just ask your AI assistant naturally:

"Analyze my BaZi chart — I was born on March 15, 1990 at 2pm"

"What does the Chinese almanac say about today?"

"Do a three-card tarot reading about my career change"

Example Responses

BaZi Analysis

User: Analyze my birth chart — born 1990-05-15 at 14:00

→ Tool: bazi_analysis({ birthDate: "1990-05-15", birthHour: 14 })
→ Returns: Four Pillars chart with heavenly stems/earthly branches,
  five elements breakdown (金2 木1 水1 火1 土3), day master analysis,
  and personalized life reading

Tarot Reading

User: Draw a three-card spread about my relationship

→ Tool: tarot({ question: "relationship outlook", spread: "three" })
→ Returns: Three cards with names, positions (upright/reversed),
  individual meanings, and a comprehensive interpretation

Chinese Almanac

User: Is today a good day to sign a contract?

→ Tool: almanac({ date: "2026-03-17" })
→ Returns: Lunar date, auspicious activities (宜), inauspicious activities (忌),
  hourly fortune breakdown, and daily summary

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | GUANXING_API_KEY | Yes | Your GuanXing API key. Get one at heartai.zeabur.app |

Development

# Clone
git clone https://github.com/doggychip/guanxing-mcp.git
cd guanxing-mcp

# Install & build
npm install
npm run build

# Run locally
GUANXING_API_KEY=your-key node dist/index.js

How It Works

This package implements the Model Context Protocol (MCP) standard using stdio transport — the standard for MCP CLI tools. When an MCP client (like Claude Desktop) starts this server, it communicates over stdin/stdout to discover and invoke tools.

Each tool call is forwarded to the GuanXing API at https://heartai.zeabur.app/api/v1/... with your API key for authentication. The AI-generated metaphysics readings are returned directly to your assistant for natural conversation.

License

MIT