@guanxing1/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", "@guanxing1/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", "@guanxing1/mcp-server"],
      "env": {
        "GUANXING_API_KEY": "your-api-key-here"
      }
    }
  }
}

Cursor

Open Settings > MCP and add:

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

Cline (VS Code)

Edit your Cline MCP settings:

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

Windsurf

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

{
  "mcpServers": {
    "guanxing": {
      "command": "npx",
      "args": ["-y", "@guanxing1/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