GuanXing (观星) — Chinese Metaphysics AI Tools

@guanxing1/mcp-server

Servidor MCP para 观星 (GuanXing) — Ferramentas de metafísica chinesa com IA para assistentes de LLM.

Dê ao seu assistente de IA acesso a BaZi (八字), Tarô, adivinhação do I-Ching (求签), Feng Shui, interpretação de sonhos, calendário chinês e muito mais — tudo através do Model Context Protocol.

---

O que é 观星 (GuanXing)?

GuanXing é uma plataforma de metafísica chinesa com IA que combina milhares de anos de sabedoria oriental com IA moderna. Ela fornece leituras precisas e personalizadas em múltiplas disciplinas metafísicas — desde análise de destino pelos Quatro Pilares até leituras de cartas de tarô.

Este servidor MCP conecta seu assistente de IA (Claude, GPT, etc.) diretamente à API do GuanXing, para que você possa fazer perguntas como:

• "O que meu mapa BaZi diz sobre minha carreira?"
• "Faça uma leitura de tarô para minha pergunta sobre relacionamento"
• "Hoje é um dia auspicioso para assinar um contrato?"
• "Analise o feng shui do meu home office voltado para o sul"

---

Ferramentas Disponíveis

Ferramenta	Descrição
bazi_analysis	Analisa os Quatro Pilares chineses (八字) com base na data e hora de nascimento. Retorna troncos celestes, ramos terrestres, cinco elementos e análise do mestre do dia.
daily_fortune	Sorte diária personalizada por signo do zodíaco. Pontuações para carreira, amor, riqueza, saúde, além de cor e número da sorte.
qiuqian	Sorteio de voto divino (求签) — adivinhação tradicional com varetas de templo, incluindo poema e interpretação. Escolha entre estilo Guanyin ou Guandi.
almanac	Consulta ao calendário chinês (黄历). Data lunar, atividades auspiciosas/inauspiciosas, sorte por hora e resumo diário.
dream_interpret	Interpretação de sonhos combinando a tradição de Zhou Gong (周公解梦) com a psicologia moderna. Símbolos, significado e conselhos.
tarot	Leitura de tarô com tiragens de uma carta, três cartas ou cruz celta. Significados completos das cartas e interpretação abrangente.
name_score	Pontuação de nomes chineses usando a numerologia dos Cinco Elementos (五格剖象法). Pontuação total, detalhamento dos elementos e análise dos cinco elementos.
fengshui	Avaliação de feng shui para casa, escritório ou loja. Pontuação, sugestões, itens de sorte e coisas a evitar.
compatibility	Análise de compatibilidade entre duas pessoas com base em informações de nascimento, zodíaco ou nomes. Pontuação multidimensional.
zodiac	Análise aprofundada do signo do zodíaco — traços de personalidade, elemento, planeta regente e compatibilidade entre signos.
community_browse	Navegue pelas postagens mais recentes da comunidade no GuanXing.
community_post	Crie uma nova postagem na comunidade GuanXing.

---

Início Rápido

1. Obtenha uma Chave de API

Registre-se em heartai.zeabur.app e crie uma chave de API nas configurações de desenvolvedor.

2. Configure Seu Cliente MCP

Adicione o servidor à configuração do seu cliente MCP:

Claude Desktop

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

Edite ~/.claude/settings.json ou .mcp.json no seu projeto:

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

Cursor

Abra Configurações > MCP e adicione:

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

Cline (VS Code)

Edite as configurações MCP do Cline:

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

Windsurf

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

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

3. Comece a Usar

Depois de configurado, basta perguntar ao seu assistente de IA naturalmente:

"Analise meu mapa BaZi — nasci em 15 de março de 1990 às 14h"

"O que o calendário chinês diz sobre hoje?"

"Faça uma leitura de tarô de três cartas sobre minha mudança de carreira"

---

Exemplos de Respostas

Análise 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

Leitura de Tarô

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

Calendário Chinês

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

---

Variáveis de Ambiente

Variável	Obrigatória	Descrição
GUANXING_API_KEY	Sim	Sua chave de API do GuanXing. Obtenha uma em heartai.zeabur.app

---

Desenvolvimento

# 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

---

Como Funciona

Este pacote implementa o padrão Model Context Protocol (MCP) usando transporte stdio — o padrão para ferramentas MCP CLI. Quando um cliente MCP (como o Claude Desktop) inicia este servidor, ele se comunica via stdin/stdout para descobrir e invocar ferramentas.

Cada chamada de ferramenta é encaminhada para a API do GuanXing em https://heartai.zeabur.app/api/v1/... com sua chave de API para autenticação. As leituras metafísicas geradas por IA são retornadas diretamente ao seu assistente para conversa natural.

---

Licença

MIT