GetBirthChart MCP

Servidor MCP oficial para cálculos estructurados de carta natal, posiciones planetarias, Big Three, signo lunar, signo ascendente, aspectos y sinastría a través de GetBirthChart.

GitHub

Documentación

@getbirthchart/mcp

Servidor MCP oficial 0.2.0 para cálculos astrológicos de GetBirthChart. Proporciona a clientes de IA compatibles con MCP acceso a cálculos estructurados a través de la API pública de GetBirthChart; no contiene ni reimplementa el motor de astrología.

Requisitos

Node.js 20 o superior
Una clave de API de desarrollador de GetBirthChart

Crea una clave en getbirthchart.com/developers. Mantenla privada y no confirmes configuraciones de host MCP que contengan la clave real.

Inicio rápido

El paquete se ejecuta a través de MCP stdio y puede lanzarse con npx:

{
  "mcpServers": {
    "getbirthchart": {
      "command": "npx",
      "args": ["-y", "@getbirthchart/mcp@0.2.0"],
      "env": {
        "GETBIRTHCHART_API_KEY": "gbc_live_your_key_here"
      }
    }
  }
}

Esta es la configuración estándar basada en comandos para hosts que admiten servidores MCP stdio. Usa la documentación actual de tu cliente para la ubicación exacta del archivo de configuración o de la interfaz; este repositorio ha sido probado a nivel de protocolo con el cliente oficial de MCP TypeScript, no con clientes específicos de proveedores.

Variables de entorno

Variable	Obligatoria	Descripción
`GETBIRTHCHART_API_KEY`	Sí	Clave de API de desarrollador del lado del servidor.
`GETBIRTHCHART_API_BASE_URL`	No	Anulación de la URL base de la API HTTPS para desarrollo/pruebas. HTTP solo se acepta para localhost.

La clave se lee al inicio, nunca se acepta como argumento de herramienta y nunca se escribe en stdout, registros, recursos o resultados de herramientas.

Herramientas disponibles

Todas las herramientas son de solo lectura y devuelven hechos de cálculo estructurados. Las entradas usan campos estrictos: date, opcionales time y place, obligatorios latitude, longitude y timezone, además de opcionales unknown_time y configuraciones de cálculo documentadas a continuación.

Herramienta	Entrada	Salida	¿Requiere hora exacta?	Comportamiento con hora desconocida
`calculate_birth_chart`	`birthData`	Carta natal mapeada	No	Omite Ascendente y casas; conserva la incertidumbre.
`get_planet_positions`	`birthData`	Posiciones planetarias	No	Conserva la incertidumbre de la carta.
`get_big_three`	`birthData`	Sol, Luna y Ascendente opcional	No	No adivina el Ascendente.
`get_moon_sign`	`birthData`	Signo lunar e incertidumbre	No	Devuelve ambigüedad cuando el backend no puede establecer un único signo.
`get_rising_sign`	`birthData`	Signo ascendente	Sí	Devuelve `birth_time_required`.
`calculate_aspects`	`birthData`	Aspectos natales	No	Devuelve solo hechos del backend.
`calculate_synastry`	`person_a`, `person_b`, campos de relación	Aspectos y resúmenes de sinastría	Por persona	Conserva los límites de hora desconocida de cada persona.

La API pública actual no geocodifica place; proporciona latitud, longitud y una zona horaria IANA incluso cuando se incluye una etiqueta de lugar. El servidor MCP nunca inventa una hora de nacimiento. El backend puede usar la medianoche local como ancla de cálculo etiquetada para una evaluación de hora desconocida, pero nunca presenta esa ancla como la hora de nacimiento de la persona y nunca adivina casas, el Ascendente o un signo lunar ambiguo.

Ejemplo de entrada:

{
  "date": "1990-01-15",
  "time": "12:00",
  "place": "New York, NY",
  "latitude": 40.7128,
  "longitude": -74.006,
  "timezone": "America/New_York"
}

Hora desconocida:

{
  "date": "1990-01-15",
  "unknown_time": true,
  "latitude": 40.7128,
  "longitude": -74.006,
  "timezone": "America/New_York"
}

Opciones de cálculo

Las herramientas natales aceptan las opciones principales expuestas gbc-astro 1.13.0 house_system, node_type, aspect_preset, custom_aspect_rules, additional_points, fold, zodiac y ayanamsa. Omítelas para los valores predeterminados compatibles con versiones anteriores: Tropical, Placidus, Nodo Verdadero, aspectos estándar, Chiron activado y Lilith desactivado. Los cálculos sidéreos requieren un ayanamsa con nombre; Lahiri es la opción de producto recomendada. Los aspectos personalizados requieren custom_aspect_rules y cada regla usa type, exact_angle y orb.

La implementación expone los sistemas de casas relevantes para el producto del núcleo (placidus, whole_sign, equal) además de los sistemas registrados del motor, Nodo Medio, aspectos natales Estándar/Extendido/Personalizado, Lilith Media/Verdadera, solicitudes de Vértice y Parte de la Fortuna, y ayanamsas sidéreos con nombre. El contrato MCP no añade lógica de cálculo ni interpretación. Compuesta y Davison son operaciones del núcleo/SDK pero no son herramientas MCP en esta versión.

La sinastría acepta un node_type a nivel de relación para que ambas cartas usen una convención de nodo, además de opcionales relationship_type, topic y target_instant. El servidor conserva los metadatos de respuesta y los campos aditivos del esquema 1.x. Una respuesta HTTP natal puede omitir calculationHash; eso es válido y nunca es obligatorio. El servidor conserva un hash de cálculo v2: devuelto sin cambiarlo ni truncarlo. La compatibilidad principal es el esquema natal 1.9.0 y el esquema de sinastría 1.5.0.

Recursos

getbirthchart://methodology — convenciones de cálculo y límites de hora desconocida.
getbirthchart://data-sources — procedencia de efemérides, zona horaria y entrada de ubicación.
getbirthchart://engine-info — metadatos del proveedor y de la API pública.

Referencias web autorizadas: Metodología y Fuentes de datos.

Errores

Los fallos de herramientas usan datos estructurados error con un code seguro legible por máquina, mensaje, retryable y opcional retry_after. Los códigos comunes incluyen validation_error, authentication_required, birth_time_required, location_not_found, ambiguous_location, rate_limit_exceeded, timeout y internal_error.

Solución de problemas

Clave de API faltante: establece GETBIRTHCHART_API_KEY en el entorno del servidor del host MCP; nunca es un argumento de herramienta.
Errores de autenticación o límite de velocidad: usa el error estructurado code y retry_after cuando estén presentes. No pongas la clave en una llamada de herramienta ni en un registro de cliente.
Validación de hora desconocida: omite time cuando unknown_time es true; el servidor no sustituirá el mediodía ni inventará un signo ascendente.
Validación de ubicación: incluye latitude, longitude numéricos WGS84 y una timezone IANA; place es solo una etiqueta y no se geocodifica aquí.
Desarrollo local: usa GETBIRTHCHART_API_BASE_URL solo con HTTPS, o HTTP en localhost. Nunca envíes una clave de producción a un host no confiable.

Privacidad y seguridad

Los datos de nacimiento se pasan solo a la API pública configurada para el cálculo solicitado. Este paquete no persiste, almacena en caché ni registra entradas de nacimiento, y no tiene análisis ni telemetría. La anulación opcional de la URL base cambia el límite de confianza; no envíes una clave de producción a un host no confiable.

Reporta problemas de seguridad de forma privada a través del proceso en SECURITY.md. No incluyas claves de API en informes de errores.

Desarrollo

npm install
npm run lint
npm run typecheck
npm test
npm run build

Las pruebas usan clientes simulados y no llaman a la API de producción. Para ejecutar el servidor compilado localmente, establece GETBIRTHCHART_API_KEY y ejecuta node dist/cli.js; el tráfico normal del protocolo permanece en stdout, mientras que los fallos de inicio se escriben en stderr.

Enlaces

Metadatos del registro MCP

Los metadatos del registro se preparan en server.json con el nombre de servidor io.github.getbirthchart-com/getbirthchart-mcp. Publica primero el paquete npm, luego autentícate con la herramienta oficial mcp-publisher y publica los metadatos. El envío al registro no forma parte intencionalmente de la compilación del paquete ni del flujo de trabajo de CI.