AstroWay MCP

MCP abrangente de astrologia com suporte da API de Cálculo AstroWay — mapa natal, sinastria, trânsitos, dashas védicas (Vimshottari/Yogini/Ashtottari/Kalachakra), Tarot (Rider-Waite-Smith / Marseille / Lenormand), Numerologia, Design Humano, horóscopos com IA. Precisão subarcosegundo da Efemérides Suíças. 10.000 créditos gratuitos/mês, sem necessidade de cartão. Instalação: npx @astroway/mcp

GitHub

Experimente este MCPPatrocinado

Documentação

@astroway/mcp

Servidor MCP (Model Context Protocol) que expõe todos os endpoints da AstroWay Calculation API como ferramentas para Claude Desktop, Cursor e qualquer agente de IA compatível com MCP.

Mapas natais, sinastria, trânsitos, dashas védicas (Vimshottari, Yogini, Ashtottari, Kalachakra), 16 Vargas, Tarot (Rider-Waite / Marseille / Lenormand), Numerologia (5 sistemas), Human Design, horóscopos com IA — tudo encapsulado como ferramentas MCP que o agente pode chamar diretamente.

As ferramentas são geradas automaticamente a partir do manifesto da API em tempo de build, então cada versão inclui todos os endpoints que existem em produção. Sem manutenção manual de listas de ferramentas.

Instalação

Claude Desktop

Adicione em ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ou %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "astroway": {
      "command": "npx",
      "args": ["-y", "@astroway/mcp"],
      "env": {
        "ASTROWAY_API_KEY": "aw_live_..."
      }
    }
  }
}

Reinicie o Claude Desktop. O servidor astroway aparecerá no indicador MCP na parte inferior do campo de entrada do chat.

Cursor

Adicione em ~/.cursor/mcp.json:

{
  "mcpServers": {
    "astroway": {
      "command": "npx",
      "args": ["-y", "@astroway/mcp"],
      "env": { "ASTROWAY_API_KEY": "aw_live_..." }
    }
  }
}

Cline / Continue / Windsurf / Copilot / VS Code MCP

O mesmo comando npx @astroway/mcp funciona em qualquer cliente compatível com MCP. Coloque este bloco no arquivo de configuração MCP do cliente (o caminho varia conforme o cliente):

{
  "mcpServers": {
    "astroway": {
      "command": "npx",
      "args": ["-y", "@astroway/mcp"],
      "env": { "ASTROWAY_API_KEY": "aw_live_..." }
    }
  }
}

Locais de configuração:

Cliente	Caminho de configuração
Cline (VS Code)	`.cline/mcp.json` na raiz do workspace
Continue	`~/.continue/config.json` (em `mcpServers`)
Windsurf	`~/.codeium/windsurf/mcp_config.json`
GitHub Copilot Chat (VS Code)	habilite a pré-visualização nas configurações e depois `mcp.json` no workspace
Extensão MCP do VS Code	`~/.vscode/mcp.json`

Outros clientes MCP

Execute como servidor stdio:

ASTROWAY_API_KEY=aw_live_... npx @astroway/mcp

Privacidade

Este servidor MCP não faz "phone home". Não há telemetria, nem analytics, nem relatórios de uso, nem alternância de opt-in / opt-out para manter. O único tráfego de rede que o servidor origina são as chamadas à API AstroWay que você pede para ele fazer, indo diretamente da sua máquina para https://api.astroway.info/v1.

As requisições de saída carregam dois cabeçalhos de identificação para que o backend da AstroWay possa distinguir tráfego MCP de tráfego HTTP bruto em seus próprios logs:

User-Agent: astroway-mcp/<version> (Node/<node-version>)
X-Astroway-Channel: mcp

Nenhum dos cabeçalhos carrega ID de sessão, impressão digital da máquina ou qualquer dado pessoal. Eles espelham a semântica padrão de User-Agent do HTTP: toda ferramenta CLI já envia informações semelhantes.

Registro de subconjunto (avançado)

Se você usa apenas parte do catálogo, pode registrar um subconjunto e manter sua janela de contexto do LLM enxuta:

{
  "env": {
    "ASTROWAY_API_KEY": "aw_live_...",
    "ASTROWAY_TOOL_GROUPS": "western,vedic,relational",   // only these prefixes
    "ASTROWAY_READONLY": "1"                               // skip ai/horoscope/reports (LLM-backed, costs credits)
  }
}

Grupos comuns: western, vedic, tarot, numerology, hd (Human Design), relational (sinastria/composite/davison), prognostics (trânsitos/progressões/retornos), aspects, horary, geo, chinese, bazi, mayan, iching, runes, geomancy. Execute npx @astroway/mcp --list-tools para inspecionar o conjunto completo; o campo filters: … da linha de inicialização mostra o que foi aplicado.

ASTROWAY_READONLY=1 pula os três grupos que internamente chamam um LLM (ai, horoscope, reports), útil quando você quer matemática de mapa puramente determinística sem gastar créditos em geração de texto.

Modo de descoberta (enxuto)

Se o seu agente atingir os limites de contexto ou de contagem de ferramentas com o catálogo completo, defina ASTROWAY_DISCOVERY_MODE=1. Em vez de registrar 600+ ferramentas antecipadamente, o servidor expõe apenas duas meta-ferramentas:

astroway_find_tool(query, limit?): busca por palavra-chave em todo o catálogo; retorna as ferramentas com melhor correspondência, com descrição de uma linha e nomes dos parâmetros de entrada.
astroway_call_tool(name, arguments?): invoca qualquer ferramenta que a busca tenha encontrado.

O agente descobre a ferramenta certa sob demanda e depois a chama, alcançando todo o catálogo a partir de uma pegada de duas ferramentas.

Compensação: uma ferramenta despachada via astroway_call_tool retorna seu resultado apenas como texto. Uma chamada despachada em tempo de execução não pode declarar um outputSchema por chamada, então não pode carregar o structuredContent validado que ferramentas registradas diretamente fornecem. Deixe ASTROWAY_DISCOVERY_MODE não definido (o padrão) quando você quiser saída estruturada tipada; use-o quando a pressão pela contagem de ferramentas for mais importante. A descoberta substitui ASTROWAY_TOOL_GROUPS / ASTROWAY_READONLY.

Estabilidade

O catálogo é congelado durante a sessão. As 624 ferramentas, 12 prompts e 14 recursos são embutidos no pacote npm publicado e não mudam em tempo de execução. (A capacidade MCP listChanged é anunciada pelo SDK, mas nenhuma notificação */list_changed é emitida por este build. Se o seu cliente armazenar o catálogo em cache após o primeiro tools/list, ele permanecerá correto durante toda a conexão.)
Os identificadores de ferramentas são estáveis dentro de uma versão principal. Um nome publicado sob astroway_<group>_<tool> não será renomeado ou removido dentro do mesmo minor v0.x sem uma nota de depreciação em CHANGELOG.md. Entre saltos de versão principal (v1 → v2), qualquer mudança que quebre compatibilidade é anunciada e o escape legado (MCP_FLAT_TOOLS=1) te carrega por um minor.
A forma de entrada das ferramentas é estável dentro de um minor. Aperto (regex, intervalo, enum) é publicado em patches; adicionar campos obrigatórios exige um bump de minor.
Atualize o catálogo reinstalando. npm i -g @astroway/mcp@latest (ou a forma npx -y @astroway/mcp já presente na configuração do seu cliente) puxa o conjunto atual na próxima inicialização.

Verifique a instalação

Após reiniciar seu cliente MCP:

Abra o indicador MCP (parte inferior do campo de entrada do chat no Claude Desktop, barra de status no Cursor).
Você deve ver astroway listado como servidor ativo.
Passe o mouse ou clique, e o selo mostrará 624 tools registered + 12 prompts + 14 resources (contagens da versão mais recente).
A inicialização a frio leva 2-3 segundos na primeira vez (Node + handshake TLS para api.astroway.info).
Verificação rápida de qualquer terminal: npx @astroway/mcp --version imprime a versão do pacote, npx @astroway/mcp --list-tools synastry imprime as ferramentas correspondentes.

Se o servidor não aparecer, defina LOG_LEVEL=debug no bloco env acima e reinicie: a linha de inicialização e quaisquer erros de inicialização aparecerão no painel de depuração MCP do cliente.

Obtenha uma chave de API

Cadastre-se em https://api.astroway.info/dashboard/sign-up: 10 000 créditos/mês grátis, sem necessidade de cartão. Cada requisição custa 5–500 créditos dependendo do endpoint (veja preços).

Para testes locais sem plano pago, use uma chave de sandbox (aw_test_...), que retorna respostas determinísticas gratuitamente.

O que você obtém

Categorias de ferramentas, com exemplos abaixo. Execute npx @astroway/mcp uma vez e peça ao agente "liste ferramentas astroway" para o inventário completo ao vivo (o pacote sincroniza automaticamente com a API a cada versão).

Categoria	Exemplos
Núcleo	mapa natal, posições planetárias, draconico, harmônicos
Comparações	sinastria, composite, davison, compatibilidade entre sistemas
Prognósticos	trânsitos, progressões secundárias, retorno solar/lunar, calendário de trânsitos
Mapas Especializados	heliocêntrico, sideral, busca de eclipses
Aspectos & Pontos	tabela de aspectos, antiscia, pontos médios, partes árabes, estrelas fixas
Calendário & Ciclos	períodos retrógrados, ingresses, fases lunares, horas planetárias
Dignidades & Recepções	dignidades essenciais, almuten, hyleg, dispositors
Horária	mapa horário, lua fora de curso, via combusta
Human Design	mapa completo, trânsitos, penta, dream rave, perfil hologenético
Astro-Geografia	astrocartografia, espaço local, mapa de realocação
Védico	16 Vargas, Panchang, Shadbala, 4 sistemas de Dasha × 5 níveis (Vimshottari / Yogini / Ashtottari / Kalachakra), Yogas, Doshas, Compatibilidade, Muhurat
Tarot	baralhos Rider-Waite-Smith, Marseille, Lenormand; tiragens + consultas de cartas
Numerologia	Pitagórica, Caldeia, Cabalística, Védica, Matriz do Destino
Esotérico	I Ching, símbolos sabianos, dados da fortuna, correspondências de cores e pedras
Referência	signos, planetas, casas, aspectos, nakshatras, Partes Helenísticas, textos natais (cópia editorial interpretada, sem IA)
Interpretações com IA	natal, sinastria, trânsitos; chat fundamentado no mapa com quatro personas; 21 idiomas
Horóscopo	diário, semanal, mensal, compatibilidade (baseado em signos do zodíaco)

Exemplos de prompts

Após conectar o servidor, experimente estes no Claude Desktop:

Mapa natal

Calcule um mapa natal para mim, nascido em 1990-03-15 às 14:30 em Kyiv, Ucrânia (50.45N 30.52E, UTC+2). Identifique meu sol, lua, ascendente e quaisquer aspectos exatos.

Sinastria

Compare dois mapas: pessoa A nascida em 1988-06-10 09:15 em Londres (51.51N -0.13E UTC+1), pessoa B nascida em 1991-11-22 22:40 em Berlim (52.52N 13.40E UTC+1). Quais são os cross-aspectos mais fortes?

Vimshottari Dasha Védico

Execute um Vimshottari Mahadasha para alguém nascido em 1985-07-22 06:45 em Mumbai (19.07N 72.87E UTC+5.5). Em qual período planetário essa pessoa está agora (maio de 2026)?

Previsão de trânsitos

Quais trânsitos importantes de planetas externos atingem meu mapa natal em 2027-01-01? Nascimento: 1990-03-15 14:30 Kyiv (50.45 30.52 UTC+2).

Leitura de Tarot

Faça uma tiragem de 3 cartas Passado-Presente-Futuro do baralho Rider-Waite para a pergunta "devo aceitar o novo emprego?". Use a semente 42 para reprodutibilidade.

Human Design

Qual é o tipo, estratégia e autoridade de Human Design para alguém nascido em 1990-03-15 14:30 Kyiv (50.45 30.52 UTC+2)? Liste os centros definidos e a cruz de encarnação.

Chat fundamentado no mapa

Usando astroway_mcp_ai_chat, pergunte o que meu posicionamento de Saturno significa. Nascido em 1990-03-15 14:30 Kyiv (50.45 30.52 UTC+2). A resposta deve citar a casa e os orbes de aspecto em que se baseia.

Configuração

Variável de ambiente	Padrão	Descrição
`ASTROWAY_API_KEY`	(obrigatório)	Sua chave de API. Produção: `aw_live_...`. Sandbox: `aw_test_...`.
`ASTROWAY_BASE_URL`	`https://api.astroway.info/v1`	Substituição para instâncias self-hosted / staging.

Como as ferramentas são geradas

Um script em tempo de build lê o manifesto canônico de endpoints da API de produção, classifica cada endpoint pela forma de entrada (chart, twoChart, chartTarget, horoscopeSign, year, date, generic) e emite uma definição de ferramenta tipada. O servidor MCP então registra cada entrada contra um Tool com o esquema de entrada Zod apropriado.

Quando a API lança novos endpoints, a próxima versão MCP os inclui automaticamente, sem definições manuais de ferramentas para manter em sincronia.

Solução de problemas

O Claude Desktop não mostra o servidor. Verifique a parte inferior do campo de entrada do chat para o indicador MCP (ícone de controle deslizante). Clique nele para ver os servidores registrados e quaisquer erros de inicialização. Se astroway estiver ausente, execute o comando npx @astroway/mcp manualmente em um terminal, onde erros de inicialização são impressos em stderr.

As ferramentas retornam Error 401. A chave de API está ausente, inválida ou revogada. Gere uma nova em https://api.astroway.info/dashboard/keys.

As ferramentas retornam Error 402. Sem créditos no plano gratuito. Faça upgrade em https://api.astroway.info/pricing/ ou aguarde a redefinição mensal.

As ferramentas retornam Error 422 com erros de validação de campos. O LLM passou um corpo que a API não aceitou. Peça ao Claude para tentar novamente com o corpo de exemplo mostrado na descrição da ferramenta, ou use a chave de sandbox (aw_test_...) para depurar sem gastar créditos.

Estrutura do repositório

Este repositório é a vitrine pública para @astroway/mcp: README, CHANGELOG, LICENSE, instruções de instalação. O código executável é o próprio pacote npm publicado: instale-o com npm install @astroway/mcp ou execute via npx @astroway/mcp.

O código-fonte é mantido no monorepo privado da AstroWay para que o gerador em tempo de build possa ler o manifesto canônico de endpoints do workspace da API ao lado. O pacote gerado é open source sob MIT e publica cada versão no npm.

Changelog

Veja CHANGELOG.md.

Licença

MIT, veja LICENSE.