GuanXing (观星) — Chinese Metaphysics AI Tools

@guanxing1/mcp-server

Servidor MCP para 观星 (GuanXing) — Herramientas de metafísica china impulsadas por IA para asistentes LLM.

Dale a tu asistente de IA acceso a BaZi (八字), Tarot, adivinación del I-Ching (求签), Feng Shui, interpretación de sueños, almanaque chino y más, todo a través del Model Context Protocol.

---

¿Qué es 观星 (GuanXing)?

GuanXing es una plataforma de metafísica china impulsada por IA que combina miles de años de sabiduría oriental con IA moderna. Proporciona lecturas precisas y personalizadas en múltiples disciplinas de la metafísica, desde el análisis del destino de los Cuatro Pilares hasta lecturas de cartas de tarot.

Este servidor MCP conecta tu asistente de IA (Claude, GPT, etc.) directamente con la API de GuanXing, para que puedas hacer preguntas como:

• "¿Qué dice mi carta BaZi sobre mi carrera?"
• "Hazme una tirada de tarot para mi pregunta sobre relaciones"
• "¿Es hoy un día propicio para firmar un contrato?"
• "Analiza el feng shui de mi oficina en casa orientada al sur"

---

Herramientas Disponibles

Herramienta	Descripción
bazi_analysis	Analiza los Cuatro Pilares chinos (八字) según la fecha y hora de nacimiento. Devuelve troncos celestiales, ramas terrenales, cinco elementos y análisis del maestro del día.
daily_fortune	Horóscopo diario personalizado por signo zodiacal. Puntuaciones para carrera, amor, riqueza, salud, además de color y número de la suerte.
qiuqian	Saca un oráculo divino (求签) — adivinación tradicional con varillas de la suerte del templo con poema e interpretación. Elige el estilo Guanyin o Guandi.
almanac	Consulta del almanaque chino (黄历). Fecha lunar, actividades auspiciosas/desfavorables, fortuna por horas y resumen diario.
dream_interpret	Interpretación de sueños que combina la tradición de Zhou Gong (周公解梦) con la psicología moderna. Símbolos, significado y consejos.
tarot	Lectura de cartas de tarot con tiradas de una carta, tres cartas o cruz celta. Significados completos de las cartas e interpretación exhaustiva.
name_score	Puntuación de nombres chinos mediante la numerología de los Cinco Cuadros (五格剖象法). Puntuación total, desglose de cuadros y análisis de los cinco elementos.
fengshui	Evaluación de feng shui para hogar, oficina o tienda. Puntuación, sugerencias, objetos de la suerte y cosas a evitar.
compatibility	Análisis de compatibilidad entre dos personas según información de nacimiento, signo zodiacal o nombres. Puntuación multidimensional.
zodiac	Análisis en profundidad del signo zodiacal: rasgos de personalidad, elemento, planeta regente y compatibilidad de signos.
community_browse	Explora las últimas publicaciones de la comunidad en GuanXing.
community_post	Crea una nueva publicación en la comunidad de GuanXing.

---

Inicio Rápido

1. Obtén una Clave de API

Regístrate en heartai.zeabur.app y crea una clave de API en la configuración de desarrollador.

2. Configura tu Cliente MCP

Añade el servidor a la configuración de tu cliente MCP:

Claude Desktop

Edita ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o %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)

Edita ~/.claude/settings.json o .mcp.json en tu proyecto:

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

Cursor

Abre Configuración > MCP y añade:

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

Cline (VS Code)

Edita la configuración de MCP de Cline:

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

Windsurf

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

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

3. Empieza a Usarlo

Una vez configurado, solo pregunta a tu asistente de IA de forma natural:

"Analiza mi carta BaZi: nací el 15 de marzo de 1990 a las 2 pm"

"¿Qué dice el almanaque chino sobre hoy?"

"Haz una lectura de tarot de tres cartas sobre mi cambio de carrera"

---

Ejemplos de Respuestas

Análisis de BaZi

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

Lectura de Tarot

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

Almanaque Chino

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

---

Variables de Entorno

Variable	Requerida	Descripción
GUANXING_API_KEY	Sí	Tu clave de API de GuanXing. Obtén una en heartai.zeabur.app

---

Desarrollo

# 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

---

Cómo Funciona

Este paquete implementa el estándar Model Context Protocol (MCP) mediante transporte stdio, el estándar para herramientas CLI de MCP. Cuando un cliente MCP (como Claude Desktop) inicia este servidor, se comunica a través de stdin/stdout para descubrir e invocar herramientas.

Cada llamada a una herramienta se reenvía a la API de GuanXing en https://heartai.zeabur.app/api/v1/... con tu clave de API para autenticación. Las lecturas de metafísica generadas por IA se devuelven directamente a tu asistente para una conversación natural.

---

Licencia

MIT