AstroVisor MCP

AstroVisor MCP connects MCP-compatible AI clients to the complete AstroVisor API. It supports local stdio and production Streamable HTTP, discovers operations from the live OpenAPI document, and returns large calculation results through a compact, queryable response layer.

This repository is the protocol and server layer. For reusable personal workflows, private people profiles, interactive credential setup, and safe AI request construction, install the separate AstroVisor Skill.

Important

AstroVisor calculations require a personal dashboard API key beginning with pk-. Anonymous calculation requests are not supported. Create an account and get your API key at astrovisor.io, then provide it to your MCP client through a secure environment variable or the AstroVisor Skill private credential setup.

Configure the API key

For a direct MCP connection, make the key available to the client process:

export ASTROVISOR_API_KEY="pk-..."

For the safer profile-aware setup, install AstroVisor Skill and use its hidden key prompt:

npx --yes --package=astrovisor-skill@1.0.1 -- \
  astrovisor-skill install --target both

node "$HOME/.agents/skills/astrovisor/scripts/astrovisor-skill.mjs" \
  config set-key

node "$HOME/.agents/skills/astrovisor/scripts/astrovisor-skill.mjs" \
  doctor --json

You can also ask your agent:

Use $astrovisor. Help me securely configure my AstroVisor API key, keep it out of
chat and client configuration, then verify the MCP connection.

The agent should guide you to the hidden terminal prompt rather than asking you to paste the full key into the conversation.

AstroVisor Skill (optional workflow layer)
    ↓
AstroVisor MCP (this repository)
live OpenAPI · authentication · API calls · result retrieval
    ↓
AstroVisor API

Highlights

Six compact MCP tools covering 456 current API operations.
Live OpenAPI discovery instead of hundreds of hardcoded tool definitions.
Stdio support for Claude Desktop, Claude Code, Codex, and other local clients.
Authenticated Streamable HTTP at https://mcp.astrovisor.io/.
Exact operationId, path, query, and JSON body serialization.
Common core and birth_* request-profile normalization.
Compact, full, and summary response views with token budgets.
Filtering, projection, sorting, pagination, and targeted path retrieval.
Temporary result storage isolated by caller API key.
Optional full mode with one generated tool per OpenAPI operation.

Capabilities include natal astrology, transits, progressions, solar returns, synastry, compatibility, Jyotish, BaZi, Human Design, Gene Keys, numerology, Tarot, Lenormand, astrocartography, horary, electional, and every other operation published by the live AstroVisor OpenAPI schema.

Choose your integration

Need	Recommended setup
Personal assistant with reusable profiles	AstroVisor Skill
Cloud or generic MCP client	Remote Streamable HTTP
Claude Desktop or local stdio client	`npx astrovisor-mcp`
Backend/operator deployment	Internal JSON-RPC adapter plus public gateway
Direct Node.js dependency	`npm install astrovisor-mcp`

Requirements:

Node.js 20 or newer for local stdio;
an AstroVisor dashboard API key beginning with pk-;
an MCP client supporting stdio or Streamable HTTP.

Quick start

Remote Streamable HTTP

Endpoint:

https://mcp.astrovisor.io/

Authenticate with either:

Authorization: Bearer pk-...

or:

X-API-Key: pk-...

The compatibility endpoint https://mcp.astrovisor.io/mcp is also available. Health:

https://mcp.astrovisor.io/health

Local stdio

Run without a global installation:

ASTROVISOR_API_KEY="pk-..." \
npx --yes --package=astrovisor-mcp@5.0.0 -- astrovisor-mcp

Or install globally:

npm install --global astrovisor-mcp@5.0.0
ASTROVISOR_API_KEY="pk-..." astrovisor-mcp

For personal use, prefer the private launcher included in AstroVisor Skill. It avoids putting the key in MCP configuration or shell history.

Client configuration

Codex and ChatGPT desktop

Remote HTTP using an environment variable:

[mcp_servers.astrovisor]
url = "https://mcp.astrovisor.io/"
bearer_token_env_var = "ASTROVISOR_API_KEY"
startup_timeout_sec = 30
tool_timeout_sec = 120

Codex CLI, the IDE extension, and ChatGPT desktop share Codex MCP configuration on the same host. Verify with:

codex mcp list

In the interactive client, use /mcp.

For profile-aware workflows and generated secret-free configuration, follow the AstroVisor Skill Codex setup.

Official documentation: Codex MCP.

Claude Code

Remote HTTP:

claude mcp add --transport http --scope user astrovisor \
  https://mcp.astrovisor.io/ \
  --header "Authorization: Bearer pk-..."

Local stdio:

claude mcp add --transport stdio --scope user \
  --env ASTROVISOR_API_KEY=pk-... \
  astrovisor -- \
  npx --yes --package=astrovisor-mcp@5.0.0 -- astrovisor-mcp

Verify:

claude mcp get astrovisor
claude mcp list

Remote HTTP is the preferred transport for a cloud-hosted server. For personal credentials, the AstroVisor Skill launcher keeps the key outside Claude configuration and shell history.

Official documentation: Claude Code MCP.

Claude Desktop

Direct stdio configuration:

{
  "mcpServers": {
    "astrovisor": {
      "command": "npx",
      "args": [
        "--yes",
        "--package=astrovisor-mcp@5.0.0",
        "--",
        "astrovisor-mcp"
      ],
      "env": {
        "ASTROVISOR_API_KEY": "pk-...",
        "ASTROVISOR_URL": "https://astrovisor.io",
        "ASTROVISOR_TOOL_MODE": "compact"
      }
    }
  }
}

Restart Claude Desktop after changing claude_desktop_config.json.

For a configuration with no embedded API key, use the AstroVisor Skill Claude Desktop setup.

Compact toolset

Compact mode is the default. It keeps tool definitions small while preserving access to every live API operation.

Tool	Purpose
`astrovisor_conventions`	Read global request, alias, and response conventions
`astrovisor_openapi_search`	Search operations by intent or keyword
`astrovisor_openapi_list`	List operations by tags, path, method, or page
`astrovisor_openapi_get`	Inspect one canonical operation and request schema
`astrovisor_request`	Execute any operation by `operationId`
`astrovisor_result_get`	Retrieve a stored result or a narrow fragment

The correct discovery chain is:

astrovisor_conventions
    ↓
astrovisor_openapi_search / astrovisor_openapi_list
    ↓
astrovisor_openapi_get
    ↓
astrovisor_request
    ↓
astrovisor_result_get (when a stored or narrower result is needed)

Never guess an operation id or request body. astrovisor_openapi_get returns:

canonical operationId;
HTTP method and path;
path and query parameters;
requestBodySchema;
aliases;
required body fields;
an LLM-oriented example body.

Request contract

Call astrovisor_request with this outer envelope:

{
  "operationId": "<canonical operation id from astrovisor_openapi_get>",
  "path": {},
  "query": {},
  "body": {},
  "response": {
    "view": "compact",
    "tokenBudget": 12000,
    "store": true
  }
}

Rules:

put URL-template variables only in path;
put query-string values only in query;
put the API JSON request only in body;
preserve booleans, numbers, arrays, and objects as JSON types;
do not wrap body in data, payload, or request unless the live schema requires it;
do not send empty strings as substitutes for required fields;
use the live schema when it differs from examples or cached knowledge.

The MCP normalizes common aliases between:

datetime, latitude, longitude, location, timezone

and:

birth_datetime, birth_latitude, birth_longitude,
birth_location, birth_timezone

Normalization is a compatibility feature, not a reason to skip live schema inspection.

For a strict personal and multi-person workflow, use the AstroVisor Skill request contract.

Large results and precision retrieval

Every compact response uses the astrovisor.serialized.v2 envelope and can include:

meta.query.totalBefore, totalMatched, offset, limit, and nextCursor;
meta.availablePaths for discoverable follow-up paths;
meta.pathFound for path validation;
meta.truncated when additional retrieval is appropriate;
summary.source and summary.selected;
a temporary resultId;
token-optimized data.

Response controls:

Field	Purpose
`responsePath`	Select a subtree before other processing
`select`	Project specific fields
`where`	Filter using field/operator expressions
`sort`	Apply deterministic ordering
`cursor`	Continue cursor pagination
`responseOffset` / `responseLimit`	Offset pagination
`include` / `exclude`	Keep or omit paths
`maxItems`	Bound large arrays
`tokenBudget`	Bound serialized output
`store`	Keep the full response temporarily

Example:

{
  "operationId": "<operation id>",
  "body": {
    "<required field>": "<confirmed value>"
  },
  "response": {
    "view": "compact",
    "responsePath": "data.items",
    "select": ["date", "strength", "theme"],
    "where": {
      "strength_gte": 0.75
    },
    "sort": ["-strength", "date"],
    "responseLimit": 20,
    "tokenBudget": 12000,
    "store": true
  }
}

Retrieve the next fragment without recalculating:

{
  "resultId": "<result id>",
  "response": {
    "view": "compact",
    "responsePath": "data.items",
    "cursor": "<next cursor>",
    "select": ["date", "strength", "theme"],
    "responseLimit": 20,
    "tokenBudget": 12000
  }
}

Supported where suffixes:

_eq _ne _gt _gte _lt _lte
_in _nin
_contains _startswith _endswith
_exists _regex

If meta.pathFound is false, select a path from meta.availablePaths instead of repeating the same request.

Full tool mode

Set:

export ASTROVISOR_TOOL_MODE=full

Full mode creates one MCP tool per OpenAPI operationId and accepts several legacy operation aliases. It is useful for specialized clients but can consume too much context in clients with strict tool-definition limits. Compact mode is recommended for general use.

Environment variables

Stdio and internal adapter

Variable	Default	Purpose
`ASTROVISOR_API_KEY`	required	Dashboard API key
`ASTROVISOR_URL`	`https://astrovisor.io`	API base URL
`ASTROVISOR_OPENAPI_URL`	`<ASTROVISOR_URL>/openapi.json`	OpenAPI override
`ASTROVISOR_TOOL_MODE`	`compact`	`compact` or `full`
`ASTROVISOR_RESPONSE_VIEW`	`compact`	Default response view
`ASTROVISOR_DEFAULT_TOKEN_BUDGET`	implementation default	Serialized byte budget
`ASTROVISOR_RESULT_TTL_MS`	`1800000`	Result cache TTL
`ASTROVISOR_RESULT_MAX_ENTRIES`	`128`	Maximum cached results

Public gateway

Variable	Default	Purpose
`MCP_PUBLIC_HTTP_HOST`	`127.0.0.1`	Gateway bind host
`MCP_PUBLIC_HTTP_PORT`	`3002`	Gateway bind port
`INTERNAL_MCP_URL`	`http://127.0.0.1:3001/mcp`	Internal adapter URL
`API_KEY_VALIDATION_PATH`	`/internal/mcp/validate-api-key`	Non-billable key validation endpoint
`API_KEY_VALIDATION_CACHE_MS`	`60000`	Validation cache time
`MCP_INTERNAL_VALIDATION_TOKEN`	required	Internal validation credential

Self-hosting

The production topology is:

Remote MCP client
    ↓ TLS
Reverse proxy
    ↓ loopback
Public Streamable HTTP gateway
    ↓ loopback
Internal JSON-RPC adapter
    ↓
AstroVisor API

Build and start the two Node services:

npm ci
npm run build
npm run start:jsonrpc
npm run start:public

Operational requirements:

keep the AstroVisor API, internal adapter, and public gateway on loopback;
terminate TLS at a reverse proxy;
require MCP_INTERNAL_VALIDATION_TOKEN for key validation;
ensure key validation does not record billable API usage;
apply process supervision, memory limits, and restart policies;
never log raw caller API keys or full private request bodies.

Development

git clone https://github.com/rokoss21/astrovisor-mcp.git
cd astrovisor-mcp
npm ci
npm run build
npm run test:unit

Production OpenAPI smoke test:

ASTROVISOR_URL=https://astrovisor.io npm test

Stdio end-to-end test:

ASTROVISOR_API_KEY=pk-... npm run test:e2e:stdio

Remote end-to-end test:

MCP_URL=https://mcp.astrovisor.io/ \
ASTROVISOR_API_KEY=pk-... \
npm run test:e2e:remote

Security check:

npm audit --omit=dev

Migration from 4.3.x

AstroVisor Skill now has its own canonical repository and npm package:

GitHub: rokoss21/astrovisor-skill
npm: astrovisor-skill

Install it directly:

npx --yes --package=astrovisor-skill@1.0.1 -- \
  astrovisor-skill install --target both

Version 5.0.0 removes the bundled astrovisor-skill binary. This avoids npm binary-name collisions and gives each project a single release lifecycle. Replace commands that install the skill through astrovisor-mcp with the standalone package command above. The MCP tool and transport contracts are unchanged.

Related projects

AstroVisor Skill — profiles, onboarding, request workflows, and responsible interpretation.
AstroVisor — API, dashboard, and product.

License

MIT

Name		Name	Last commit message	Last commit date
src		src
.gitignore		.gitignore
.npmignore		.npmignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
test-interop.mjs		test-interop.mjs
test-production.cjs		test-production.cjs
test-remote-client.mjs		test-remote-client.mjs
test-stdio-client.mjs		test-stdio-client.mjs
tsconfig.json		tsconfig.json

Navigation Menu

Repository navigation

About

Repository files navigation

AstroVisor MCP

Configure the API key

Highlights

Choose your integration

Quick start

Remote Streamable HTTP

Local stdio

Client configuration

Codex and ChatGPT desktop

Claude Code

Claude Desktop

Compact toolset

Request contract

Large results and precision retrieval

Full tool mode

Environment variables

Stdio and internal adapter

Public gateway

Self-hosting

Development

Migration from 4.3.x

Related projects

License

About

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

AstroVisor MCP

Configure the API key

Highlights

Choose your integration

Quick start

Remote Streamable HTTP

Local stdio

Client configuration

Codex and ChatGPT desktop

Claude Code

Claude Desktop

Compact toolset

Request contract

Large results and precision retrieval

Full tool mode

Environment variables

Stdio and internal adapter

Public gateway

Self-hosting

Development

Migration from 4.3.x

Related projects

License

About

Topics

Resources

Stars

Watchers

Forks

Contributors

Languages