Skip to main content
Glama
Céu Natal

Céu Natal

Céu Natal

Servidor MCP que calcula mapas astrais com efemérides suíças para o seu assistente de IA interpretar.

In English. Céu Natal is an open-source Model Context Protocol server that computes natal charts, synastry, transits, progressions and solar/lunar returns with the Swiss Ephemeris, answering in Portuguese. A free public endpoint runs at https://astrologia-mcp.gustavocancado.com.br/mcp/ (no sign-up). Licensed AGPL-3.0. Setup for Claude, ChatGPT, Claude Code and Cursor in English: https://mistico.gustavocancado.com.br/en. Quick start in Claude Code: claude mcp add --transport http --scope user ceu-natal https://astrologia-mcp.gustavocancado.com.br/mcp/.

CI Licença: AGPL-3.0 Python 3.11

Por que existe

Peça um mapa astral a um assistente de IA e ele responde com segurança, mas as posições costumam ser inventadas: o modelo não tem efemérides, então chuta o signo da Lua e o ascendente. Este servidor faz a conta de verdade e devolve os números; a IA só interpreta.

Related MCP server: stellara-mcp

Use agora

Endpoint MCP público e gratuito (Streamable HTTP, sem login):

https://astrologia-mcp.gustavocancado.com.br/mcp/

Passo a passo para Claude, ChatGPT, Gemini, Manus, Cursor e n8n: https://mistico.gustavocancado.com.br/#conectar.

O que calcula

Tool

O que faz

calcular_mapa_natal

Posições, casas, ângulos, aspectos, nodos, Quíron e síntese de um mapa natal.

calcular_sinastria

Aspectos cruzados entre duas pessoas e planetas de uma nas casas da outra.

calcular_transitos

Posições numa data, aspectos com o mapa natal e destaque dos trânsitos lentos.

calcular_progressoes

Progressões secundárias (1 dia = 1 ano), com Lua e Sol progredidos.

calcular_mapa_composto

Mapa composto de duas pessoas pelo método de midpoints.

calcular_revolucao_solar

Mapa do retorno do Sol à posição natal num ano, com local da revolução.

calcular_revolucao_lunar

Próximo retorno da Lua à posição natal a partir de uma data.

listar_aspectos_tipos

Aspectos suportados, com ângulos, orbes e natureza.

healthcheck

Status e versão do servidor.

Entrada de pessoa: data (DD/MM/YYYY, obrigatória), hora (HH:MM), local ("Cidade, UF" ou "Cidade, País"), nome, is_dst. No mapa natal sem hora, o cálculo usa 12:00 no horário local, a Lua vem marcada como incerta (posicao_incerta, signo_pode_mudar) e não saem casas nem ângulos. sistema_casas é opcional: P Placidus (padrão), K Koch, W Whole Sign, E Equal, R Regiomontanus, C Campanus, O Porphyrius, B Alcabitus, M Morinus, T Topocentric. GET /tools lista as tools e os nomes dos parâmetros; o inputSchema completo vem do tools/list do MCP (qualquer cliente MCP mostra).

Exemplo

Pedido (tools/call):

{
  "name": "calcular_mapa_natal",
  "arguments": {"nome": "Ana", "data": "12/03/1990", "hora": "14:30", "local": "Belo Horizonte, MG"}
}

Trecho da resposta:

{
  "planetas": {
    "sol": {"signo": "Peixes", "grau": "21°52'", "grau_decimal": 21.8779, "posicao_absoluta": 351.8779,
            "retrogrado": false, "elemento": "Agua", "qualidade": "Mutavel", "casa": 8},
    "lua": {"signo": "Libra", "grau": "6°19'", "grau_decimal": 6.329, "posicao_absoluta": 186.329,
            "retrogrado": false, "elemento": "Ar", "qualidade": "Cardinal", "casa": 3}
  },
  "angulos": {
    "ascendente": {"signo": "Cancer", "grau": "18°38'", "grau_decimal": 18.6412, "posicao_absoluta": 108.6412}
  },
  "aspectos": [
    {"planeta_a": "lua", "planeta_b": "venus", "tipo": "trigono", "orbe": 0.48,
     "aplicando": true, "exato": true, "natureza": "harmonico"}
  ],
  "local_resolvido": {"lat": -19.9167, "lng": -43.9333, "fuso": "America/Sao_Paulo"}
}

A resposta completa traz também os outros planetas, as 12 casas, meio do céu, descendente, fundo do céu, pontos sensíveis e a síntese (elementos, qualidades, hemisférios, stelliums).

Rodar local

Com Docker:

cp .env.example .env
docker compose up --build        # http://localhost:8000

Com pip (Linux ou macOS; no Windows, use o WSL, porque o pyswisseph não compila nele):

python3.11 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.server:app --port 8000

Por stdio, para cliente que só abre processo local: python -m app.stdio (mesmas variáveis de ambiente).

Rotas: /mcp/ (MCP Streamable HTTP), /health, /tools (lista de tools; pública quando MCP_API_KEY está vazia), /llms.txt, /mapa-rapido (formulário do site) e / (redireciona para PUBLIC_SITE_URL).

Para desenvolver, instale também requirements-dev.txt e rode ruff check ., mypy app e python -m pytest -q. Detalhes em CONTRIBUTING.md.

Variáveis de ambiente

Variável

Default

Descrição

MCP_SERVER_NAME

ceu-natal

nome devolvido no initialize

MCP_SERVER_VERSION

2.2.6

versão exposta

MCP_API_KEY

(vazio)

se definida, exige Authorization: Bearer <chave>; vazia, libera tudo

MCP_ALLOWED_HOSTS

(vazio)

hosts aceitos no /mcp/ (anti-DNS rebinding), separados por vírgula; vazio = sem validação

RATE_LIMIT_SESSION_PER_MIN

30

chamadas de tool por minuto por sessão MCP (0 desliga)

RATE_LIMIT_GLOBAL_PER_MIN

600

chamadas de tool por minuto no total (0 desliga)

RATE_LIMIT_MAPA_RAPIDO_IP_PER_MIN

6

pedidos ao /mapa-rapido por minuto por IP (0 desliga)

RATE_LIMIT_MAPA_RAPIDO_GLOBAL_PER_MIN

120

pedidos ao /mapa-rapido por minuto no total (0 desliga)

PUBLIC_SITE_URL

https://github.com/gucancado/ceu-natal

destino do redirect de / e do /llms.txt (vai para <site>/llms.txt)

CORS_ORIGINS

(vazio = PUBLIC_SITE_URL)

origens aceitas pelo CORS do /mapa-rapido, separadas por vírgula

GEONAMES_USERNAME

(vazio) — sem ele só o Nominatim é usado

conta GeoNames da geocodificação (crie a sua, gratuita, em geonames.org)

NOMINATIM_USER_AGENT

ceu-natal-mcp/2.0

User-Agent enviado ao Nominatim (OSM)

NOMINATIM_MIN_INTERVAL_S

1.0

intervalo mínimo (s) entre chamadas ao Nominatim

GEOCODER_MAX_CONCORRENTES

4

teto de chamadas simultâneas aos provedores de geocodificação

GEOCODER_ESPERA_MAX_S

3.0

espera máxima (s) por uma vaga nesse teto; depois, erro

GEOCODER_CACHE_PATH

<tmp>/ceu-natal-geocode-cache.json

cache persistente de coordenadas; no Docker, volume em /var/cache/ceu-natal

CONTATOS_PATH

vazio (desliga o /contato)

arquivo JSONL dos contatos para novidades deixados no site; em produção, /var/lib/ceu-natal/contatos.jsonl (volume persistente)

ESTATISTICAS_PATH

vazio (desliga o /estatisticas)

SQLite das estatísticas agregadas de uso (página de status); em produção, /var/lib/ceu-natal/estatisticas.sqlite3 (volume persistente)

HISTORICO_PATH

vazio (nada é guardado)

SQLite dos mapas feitos no formulário do site (data, hora, cidade), ligados ao id anônimo do navegador e ao contato; em produção, /var/lib/ceu-natal/historico.sqlite3

CONTATOS_ADMIN_TOKEN

vazio (/contatos responde 404)

token Bearer das rotas GET /contatos (contatos com os mapas de cada um) e GET /historico (histórico por navegador); separado da MCP_API_KEY

Site (web/)

O site de apresentação (https://mistico.gustavocancado.com.br) é um app Next.js 16 separado, com imagem Docker própria (web/Dockerfile). Para rodar: cd web && pnpm install && pnpm dev; as URLs vêm de web/.env.example.

Precisão e limites

  • Efemérides: Swiss Ephemeris, da Astrodienst AG, via Kerykeion e pyswisseph. Zodíaco tropical.

  • Latitude acima de 66°: o cálculo de casas não é confiável perto dos polos. O mapa natal sai sem casas nem ângulos, com aviso; trânsitos, progressões e revoluções recusam.

  • Anos: datas de 1800 a 2399 (a faixa da efeméride de Quíron); revolução solar de 1800 a 2200.

  • Horário de verão: se a hora cai na transição (ambígua ou inexistente), o servidor devolve erro pedindo is_dst (true = horário de verão, false = padrão).

  • Sem hora de nascimento: cálculo às 12:00 locais; a Lua pode estar antes ou depois até metade do movimento diário dela (em geral de 6° a 7,6°, devolvido em margem_graus), e o resultado diz quando o signo dela pode mudar.

  • Limites do endpoint público: 30 chamadas por minuto por sessão e 600 por minuto no total. Nada do que chega pelo MCP é armazenado (os mapas do formulário do site ficam guardados); veja a política de privacidade.

Contribuir

Issues e pull requests são bem-vindos. Veja CONTRIBUTING.md; para falhas de segurança, SECURITY.md.

Licença

AGPL-3.0-or-later. A AGPL vale também para uso pela rede: quem oferecer este servidor como serviço modificado precisa publicar o código. O endpoint público roda exatamente o código deste repositório.

Copyright (C) 2026 Gustavo Cançado. Créditos e licenças de terceiros em NOTICE.

A escolha segue as dependências: o Kerykeion é AGPL-3.0, e o pyswisseph (Swiss Ephemeris) é distribuído sob AGPL-3.0 ou sob a licença profissional paga da Astrodienst. Um uso fora dos termos da AGPL exigiria a licença profissional da Swiss Ephemeris e trocar o Kerykeion. O site usa os pacotes @beeads/*, sob licença MIT, compatível com a AGPL.

Available Tools

9 tools
calcular_mapa_compostoMapa compostoA
Read-onlyIdempotent
Inspect

Calcula o mapa composto (composite chart) de duas pessoas pelo método de midpoints — o mapa da 'relação como entidade'. Diferente da sinastria, que compara dois mapas, o composto cria um terceiro mapa a partir dos pontos médios das longitudes planetárias. Retorna posições compostas, ângulos (ASC e MC compostos quando ambas as pessoas têm hora+local), aspectos internos do composto e síntese de elementos. Não retorna casas — composto por midpoint não tem instante/local definidos.

Inputs: pessoa_a (required), pessoa_b (required), sistema_casas.

calcular_mapa_natalMapa natalA
Read-onlyIdempotent
Inspect

Calcula o mapa astral natal completo de uma pessoa. Retorna posições planetárias, casas (Placidus por padrão; sistema configurável), ângulos, aspectos entre planetas, pontos sensíveis (nodos verdadeiros e Quíron) e síntese (elementos, qualidades, hemisférios, stelliums). Se hora ou local forem omitidos, retorna apenas posições por signo, sem casas nem ângulos. Sem hora, o cálculo usa 12:00 no horário local e a Lua vem marcada como incerta (posicao_incerta, signo_pode_mudar).

Inputs: data (required), hora, nome, local, +2 more.

calcular_progressoesProgressões secundáriasA
Read-onlyIdempotent
Inspect

Calcula as progressões secundárias (técnica 'um dia = um ano') de um mapa natal para uma data alvo. Retorna posições progredidas, aspectos entre planetas progredidos e natais, destaque para Lua progredida (fase emocional atual, ~2.5 anos por signo), Sol progredido (capítulo de vida, ~30 anos por signo), e sinaliza ingressos recentes e mudanças iminentes de signo.

Inputs: natal (required), data_alvo (required), sistema_casas.

calcular_revolucao_lunarRevolução lunarA
Read-onlyIdempotent
Inspect

Calcula a revolução lunar (lunar return) — o mapa do instante exato em que a Lua retorna à longitude que ocupava no nascimento, técnica de previsão mensal com ciclo de ~27,3 dias. Retorna o primeiro retorno lunar a partir da data de referência informada, com mapa completo, aspectos com o natal, sobreposição dos dois mapas e destaques centrados na Lua: casa que ela ocupa, ascendente da revolução e seus regentes, planetas angulares. Exige hora e local de nascimento. O parâmetro local_revolucao é obrigatório.

Inputs: natal (required), data_referencia (required), local_revolucao (required), sistema_casas.

calcular_revolucao_solarRevolução solarA
Read-onlyIdempotent
Inspect

Calcula a revolução solar (solar return) de um ano — o mapa do instante exato em que o Sol retorna à longitude que ocupava no nascimento, técnica de previsão anual. Rege o período até a revolução seguinte. Retorna o mapa completo da revolução (planetas, casas, ângulos, aspectos internos), os aspectos entre a revolução e o mapa natal, a sobreposição dos dois mapas e destaques da leitura: ascendente da revolução e seus regentes, casa ocupada pelo Sol e planetas angulares. Exige hora e local de nascimento. O parâmetro local_revolucao é obrigatório e define ascendente, meio do céu e casas — as posições planetárias são as mesmas em qualquer lugar do mundo.

Inputs: ano (required), natal (required), local_revolucao (required), sistema_casas.

calcular_sinastriaSinastriaA
Read-onlyIdempotent
Inspect

Calcula a sinastria entre duas pessoas: aspectos cruzados (planetas de A vs planetas de B), em quais casas do mapa de uma cada planeta da outra cai, e síntese com contagem de aspectos harmônicos / tensão / neutros. Útil para análise de relacionamento.

Inputs: pessoa_a (required), pessoa_b (required), sistema_casas.

calcular_transitosTrânsitosA
Read-onlyIdempotent
Inspect

Calcula os trânsitos planetários para uma data específica em relação a um mapa natal. Retorna a posição atual dos planetas, aspectos entre planetas em trânsito e planetas natais (com aplicando/separando), em qual casa natal cada planeta em trânsito está caindo, e síntese com destaque para trânsitos de planetas lentos (Saturno, Urano, Netuno, Plutão e Quíron) com orbe < 2°.

Inputs: natal (required), data_transito (required), hora_transito, sistema_casas, +1 more.

healthcheckVerificar o servidorA
Read-onlyIdempotent
Inspect

Verifica se o servidor está operacional e retorna a versão.

Inputs: no named parameters. Returns: status, versao, transporte, codigo_fonte, +1 more

listar_aspectos_tiposTipos de aspectoA
Read-onlyIdempotent
Inspect

Retorna os tipos de aspectos suportados pelo servidor com seus ângulos, orbes padrão (e orbes ampliados quando há luminar), e natureza (harmônico, tensão ou neutro).

Inputs: no named parameters. Returns: aspectos

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 9 tools

    Disambiguation5/5

    Each tool targets a clearly distinct astrological calculation or support function. The overlap-prone pair sinastria vs. mapa composto is explicitly differentiated, and solar/lunar returns are cleanly separated by technique and timeframe.

    Naming Consistency4/5

    Most tools follow a clear verb_noun pattern in Portuguese, such as calcular_* and listar_*. The only deviation is healthcheck, which is a common utility name but breaks the otherwise consistent convention.

    Tool Count5/5

    Nine tools is well within a focused, appropriate range for an astrology calculation server. Each calculation tool corresponds to a meaningful technique, with no obvious filler.

    Completeness4/5

    The surface covers the major astrological workflows: natal, synastry, transits, progressions, composite, and solar/lunar returns. Minor gaps such as standalone current-sky calculation without a natal reference or chart rendering are reasonable omissions rather than blocking holes.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      High-precision astrology tools for LLM agents, including natal charts, transits, progressions, synastry, and more, backed by Swiss Ephemeris.
      1
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI assistants to retrieve precise astrology calculations, including natal charts, transits, composites, harmonic midpoints, and ranked daily aspects, using real ephemeris data rather than guesses.
      5
      1
      AGPL 3.0