Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Astronomer MCP Server find star systems similar to Kepler-186 and cluster them"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol (MCP) server providing deep LLM-agent tool and resource integration with Astronomer — an open-source computational research platform and quantitative analytical laboratory for comparative astrophysics, stellar systems, and celestial body manifolds.
The astronomer-mcp server enables AI agents (Claude Code, Cursor, Gemini CLI, etc.) to query, manipulate, cluster, and synthesize the astrophysics domain models directly over standard input/output (stdio):
51 Registered MCP Tools across 8 functional modules (Search, Cosmic Structures, Star Systems, Celestial Bodies, Clustering, Synthesis Reports, Background Jobs, and System Diagnostics).
4 Registered MCP Resources exposing read-only live platform status, catalogs, cluster snapshots, and markdown monographs.
2 MCP Prompt Templates for comparative astrophysics studies and cluster synthesis monographs.
1024-dimensional semantic manifold querying via PostgreSQL pgvector HNSW indexes.
Related MCP server: aqc-mcp
Tier / Domain | Model | Table Name | MCP Module / Tools |
Tier 1 | Galaxies & Clusters |
|
|
Tier 2 | Star Systems |
|
|
Tier 3 | Planets & Celestial Bodies |
|
|
Clustering | 15-Level Agglomerative |
|
|
Synthesis | Multi-Stage Map-Reduce |
|
|
Global Search | Cross-Catalog pgvector | Multi-table |
|
Platform | Jobs & System Info | Multi-service |
|
Node.js 20+
Running instance of Astronomer (http://localhost:3000)
git clone https://github.com/leouofa/astronomer-mcp.git
cd astronomer-mcp
npm install
npm run buildConfigure via .env file or export in your shell:
# Base URL for the Astronomer Rails API (v1)
ASTRONOMER_API_URL=http://localhost:3000/api/v1
# Optional API key if authentication is enabled
# ASTRONOMER_API_KEY=
# HTTP request timeout in milliseconds (default: 60000)
ASTRONOMER_TIMEOUT_MS=60000astronomer-mcp [options]
Options:
-u, --url <url> Astronomer API base URL (default: http://localhost:3000/api/v1)
-k, --api-key <key> Optional API key / Bearer token
-t, --timeout <ms> Request timeout in milliseconds (default: 60000)
-h, --help Display help messageAdd to your client configuration (e.g. claude_desktop_config.json or MCP settings):
{
"mcpServers": {
"astronomer": {
"command": "node",
"args": ["/path/to/astronomer-mcp/dist/index.js"],
"env": {
"ASTRONOMER_API_URL": "http://localhost:3000/api/v1"
}
}
}
}Run the Vitest test suite:
npm testThis project is licensed under the MIT License.
Compute live connected-components vector clusters for StarSystems or CelestialBodies across cosmic structures without modifying the database.
Inputs: force, level, target_type, full_coverage.
Create a new celestial body record associated with a star system.
Inputs: name (required), star_system_id (required), themes, description.
Initiate a 2-Phase Map-Reduce synthesis report on a frozen cluster snapshot.
Inputs: prompt (required), cluster_snapshot_id (required).
Compute connected-components clustering and freeze it immediately into an immutable database snapshot.
Inputs: level (required), title (required), target_type (required), full_coverage.
Create a new cosmic structure (galaxy or cluster) record in the catalog.
Inputs: name (required), description.
Create a new star system record associated with a cosmic structure.
Inputs: name (required), cosmic_structure_id (required), themes, description.
Delete a celestial body record.
Inputs: id (required).
Delete a synthesis report along with its intermediate summaries and sub-reports.
Inputs: id (required).
Delete a frozen cluster snapshot along with its cascaded cluster groups and synthesis reports.
Inputs: id (required).
Delete a cosmic structure and its cascaded star systems and celestial bodies.
Inputs: id (required).
Delete a star system and its cascaded celestial bodies.
Inputs: id (required).
Find nearest astrophysical counterparts to a specified star system or celestial body using 1024-dimensional pgvector cosine distance.
Inputs: id (required), entity_type (required), limit, star_system_id, +2 more.
Calculate 1024-dimensional vector embedding for a celestial body record.
Inputs: id (required), sync.
Initiate a 3-Phase Hierarchical Deep Synthesis monograph, reusing Phase 1 summaries from a completed parent report.
Inputs: report_id (required), batch_size.
Calculate 1024-dimensional vector embedding for a star system using the configured embedding model.
Inputs: id (required), sync.
Retrieve details of a celestial body including its structured themes and associated star system/cosmic structure.
Inputs: id (required), include_embedding.
Retrieve details of a specific archetype cluster group with all member star systems or celestial bodies.
Inputs: id (required), include_members.
Retrieve complete scholarly astrophysics report content, progress percentage, markdown monograph, and intermediate summaries.
Inputs: id (required), include_summaries, include_sub_reports.
Retrieve details of a frozen cluster snapshot including member groups and generated reports.
Inputs: id (required), include_groups, include_members, include_reports.
Retrieve details of a single cosmic structure (galaxy/cluster) including its star systems.
Inputs: id (required), include_star_systems.
Check the status, progress, and result of an ActiveJob/Sidekiq background task.
Inputs: job_id (required).
Retrieve the raw OpenAPI 3.1 specification for the Astronomer API.
Inputs: no named parameters.
Get overall platform health, catalog entity counts, embedding coverage stats, and active LLM configuration.
Inputs: no named parameters.
Retrieve a single Phase 2 batch analysis.
Inputs: id (required).
Retrieve a single Phase 1 per-cluster scholarly summary.
Inputs: id (required).
Get embedding completion metrics for StarSystems and CelestialBodies, active embedding/LLM parameters, and context window presets.
Inputs: no named parameters.
Retrieve full profile of a star system including cosmic structure, thematic astrophysical tags, and celestial bodies.
Inputs: id (required), include_embedding, include_celestial_bodies.
List and filter celestial bodies (exoplanets, moons, dwarf planets) with physical/orbital themes and embedding metadata.
Inputs: q, limit, theme, offset, +4 more.
List all archetype cluster groups belonging to a specific frozen snapshot.
Inputs: cluster_snapshot_id (required), include_members.
List generated multi-phase comparative astrophysics and celestial body manifold synthesis reports.
Inputs: limit, offset, status, is_detailed, +2 more.
List frozen archetype cluster snapshots.
Inputs: limit, offset, target_type, include_groups.
List cosmic structures (galaxies, dwarf galaxies, galaxy clusters) registered in Astronomer with star system counts.
Inputs: q, limit, offset, include_star_systems.
List recent asynchronous background jobs (embedding calculations, LLM discoveries, synthesis reports).
Inputs: limit.
List all Phase 2 intermediate batch analyses belonging to a detailed synthesis report.
Inputs: cluster_report_id (required).
List all Phase 1 per-cluster analyses belonging to a synthesis report.
Inputs: cluster_report_id (required).
List and filter star systems with astrophysical themes, celestial body counts, and vector embedding status.
Inputs: q, limit, theme, offset, +5 more.
Trigger bulk LLM celestial body discovery across all star systems or a single star system.
Inputs: sync, star_system_id.
Trigger LLM discovery to populate major galaxies and galaxy clusters with astrophysical descriptions.
Inputs: sync.
Discover and populate star systems for a specific cosmic structure via LLM generation.
Inputs: id (required), sync.
Discover and generate celestial bodies (planets, moons) for a star system via LLM extraction.
Inputs: id (required), sync.
Trigger bulk LLM star system discovery across all cosmic structures or a single cosmic structure.
Inputs: sync, cosmic_structure_id.
Unified cross-catalog semantic or keyword search across star systems and celestial bodies in the Astronomer comparative astrophysics manifold.
Inputs: q (required), mode, limit, target_type.
Enqueue bulk embedding generation for all StarSystems or CelestialBodies.
Inputs: model_type (required), only_missing.
Update an existing celestial body's attributes, star system, or thematic tags.
Inputs: id (required), name, themes, description, +1 more.
Dynamically update the active LLM context window token size.
Inputs: context_window (required).
Update an existing cosmic structure's name or description.
Inputs: id (required), name, description.
Update an existing star system's attributes, cosmic structure, or thematic tags.
Inputs: id (required), name, themes, description, +1 more.
Batch insert or update celestial bodies scoped to a specific star system.
Inputs: star_system_id (required), celestial_bodies (required).
Batch insert or update cosmic structures matching case-insensitively on name.
Inputs: cosmic_structures (required).
Batch insert or update star systems scoped to a specific cosmic structure.
Inputs: star_systems (required), cosmic_structure_id (required).
Poll a background job until completion or failure with configurable timeout.
Inputs: job_id (required), timeout_ms, poll_interval_ms.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 51 tools
Most tools are distinguishable by resource+action, but several families overlap heavily: populate_* vs upsert_*_batch vs create_* for the same entities, three separate embedding tools (generate_star_system_embedding, generate_celestial_body_embedding, trigger_bulk_embeddings), and compute_clusters vs create_cluster_snapshot vs create_cluster_report vs generate_deep_synthesis. Descriptions do help differentiate, but an agent has real risk of misselecting within these clusters.
Nearly everything follows snake_case verb_noun (list_/get_/create_/update_/delete_/populate_/generate_), which is predictable. Minor deviations like the bare 'search', 'find_counterparts', and 'compute_clusters' break the strict pattern slightly but remain readable.
51 tools is far beyond a comfortable surface for an agent to navigate. While the domain is broad (CRUD across three entities plus embeddings, clustering, reports, jobs, and settings), many tools are variants of each other (per-entity and bulk embedding/populate variants), pushing this into heavy territory.
The surface covers full lifecycle CRUD for cosmic structures, star systems, and celestial bodies, plus batch upserts, embeddings, clustering/snapshots, report generation, job polling, and settings. It is essentially exhaustive for the stated comparative-astrophysics domain with no obvious dead ends.
Astronomical logical calculator for AI clients.
Astra DB tools for agents: schema, find, vector search, guarded writes, and interactive views.
Your AI Agent's Infrastructure Layer. Connect Claude, Copilot, Codex, or ChatGPT to 200+ managed open source services. Start databases, pipelines, and applications through natural language.
Persistent memory and knowledge management for AI agents with semantic search and 50+ tools.
