# @guanxing1/mcp-server

**MCP server for [观星 (GuanXing)](https://heartai.zeabur.app)** — 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](https://modelcontextprotocol.io).

---

## 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](https://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):

```json
{
  "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:

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

#### Cursor

Open **Settings > MCP** and add:

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

#### Cline (VS Code)

Edit your Cline MCP settings:

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

#### Windsurf

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

```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](https://heartai.zeabur.app) |

---

## Development

```bash
# 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)](https://modelcontextprotocol.io) 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