Astronomy Oracle is an MCP server that provides accurate astronomical catalog data and observing tools for LLM assistants, eliminating hallucinated celestial data.
Look up celestial objects (lookup_object): Retrieve detailed data for any object by Messier number (e.g. M31), NGC/IC designation (e.g. NGC7000), or common name (e.g. Andromeda Galaxy). Returns type, RA/Dec coordinates, magnitude, angular size, surface brightness, Hubble type, and cross-references. Optionally provide latitude, longitude, and date/time to get altitude/azimuth and rise/transit/set times.
Search and filter the catalog (search_objects): Query 13,000+ deep-sky objects by type (Galaxy, Planetary Nebula, Open Cluster, etc.), constellation, magnitude range, angular size, or catalog membership (Messier, Caldwell, NGC, IC). Results are returned as a formatted table sorted by brightness (up to 100 results).
Plan observing sessions (plan_session): Generate an optimized observing plan for a specific location and date, filtering by minimum altitude, magnitude limit, and object types, with the best objects grouped into evening, midnight, and pre-dawn windows scored by observability.
Perform deterministic astronomy calculations: Compute Julian dates, sidereal time, and alt/az conversions — all processed locally without network dependencies.
Accurate astronomical catalog data and observing session planner for LLM assistants. Stops hallucinated magnitudes, coordinates, and visibility.
3 tools for object lookup, catalog search, and observing session planning
13,000+ deep-sky objects from the OpenNGC catalog (NGC, IC, Messier, and addendum objects)
Deterministic astronomy math — Julian dates, sidereal time, alt/az conversion, rise/transit/set times
Zero network dependency — all data is bundled, all calculations are local
Related MCP server: chuk-mcp-celestial
Run directly with npx:
npx astronomy-oracleOr install globally:
npm install -g astronomy-oracleAdd to your claude_desktop_config.json:
{
"mcpServers": {
"astronomy-oracle": {
"command": "npx",
"args": ["-y", "astronomy-oracle"]
}
}
}claude mcp add astronomy-oracle -- npx -y astronomy-oraclelookup_objectLook up a celestial object by Messier number, NGC/IC designation, or common name. Optionally compute visibility from a given location and time.
{
"name": "lookup_object",
"arguments": {
"name": "M31",
"latitude": 51.5,
"longitude": -0.1,
"date": "2025-06-15T22:00:00Z"
}
}Returns detailed object data: type, coordinates (RA/Dec), magnitude, angular size, surface brightness, Hubble type, cross-references, and (when location is provided) current altitude/azimuth with rise/transit/set times.
search_objectsSearch and filter the catalog by type, constellation, magnitude range, angular size, or catalog membership.
{
"name": "search_objects",
"arguments": {
"type": "PN",
"constellation": "Lyr",
"maxMagnitude": 12.0,
"limit": 10
}
}Returns a formatted table of matching objects sorted by brightness. Supports filtering by object type (Galaxy, Planetary Nebula, Open Cluster, etc.), constellation, magnitude range, minimum angular size, and catalog (Messier, Caldwell, NGC, IC).
plan_sessionGenerate an observing session plan for a given location and date. Returns the best objects to observe grouped by time window.
{
"name": "plan_session",
"arguments": {
"latitude": 40.7,
"longitude": -74.0,
"date": "2025-03-20",
"minAltitude": 20,
"maxMagnitude": 10.0,
"types": ["G", "PN", "GCl"]
}
}Returns objects grouped into three windows (evening, midnight, pre-dawn), scored by observability based on altitude, magnitude, and angular size.
Source | License | Description |
CC-BY-SA 4.0 | NGC/IC/Messier catalog with coordinates, magnitudes, dimensions, and cross-references |
The OpenNGC data is included under the Creative Commons Attribution-ShareAlike 4.0 International License. See the OpenNGC repository for full attribution.
# Run tests
npm test
# Build
npm run build
# Run in development mode (tsx)
npm run dev
# Open MCP Inspector
npm run inspectMIT for code. CC-BY-SA 4.0 for OpenNGC data.
Look up a celestial object by Messier number (e.g. M31), NGC/IC designation (e.g. NGC7000), or common name (e.g. Andromeda Galaxy). Optionally compute visibility from a given location and time.
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | Date/time in ISO 8601 format (defaults to now) | |
| name | Yes | Object name, Messier number, NGC/IC designation, or common name | |
| latitude | No | Observer latitude in degrees (-90 to 90) | |
| longitude | No | Observer longitude in degrees (-180 to 180) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses optional visibility computation based on location/time, and no side effects are expected for a read-only lookup.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the primary purpose, followed by optional behavior. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 4-parameter tool with no output schema and no annotations, the description explains the core functionality well but does not describe the return format or any defaults beyond what's in the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds value by summarizing the object name types and the optional visibility feature, which goes beyond the schema's parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool looks up a celestial object by various identifiers (Messier, NGC/IC, common name), distinguishing it from siblings like search_objects which likely perform broader searches.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you have a known object identifier or need visibility computation, but does not explicitly state when to avoid or differentiate from search_objects.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate an observing session plan for a given location and date. Returns the best celestial objects to observe grouped by time window (evening, midnight, pre-dawn), scored by observability.
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | Date in ISO 8601 format (defaults to today) | |
| types | No | Object type codes to include (e.g. ["G", "PN", "OCl"]) | |
| latitude | Yes | Observer latitude in degrees (-90 to 90) | |
| longitude | Yes | Observer longitude in degrees (-180 to 180) | |
| minAltitude | No | Minimum peak altitude in degrees (default 15) | |
| maxMagnitude | No | Maximum (faintest) visual magnitude to include |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose behavior. It describes the output (grouped by time window, scored) but does not mention any side effects, auth, or performance. Adequate for a read/generation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, no wasted words. Highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 6 parameters, 2 required, and no output schema, the description covers key output characteristics. Could mention filtering by type (from params) but not essential.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description does not add parameter-specific meaning beyond the schema overview, but no contradiction.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Generate' and resource 'observing session plan', specifying the output is grouped by time window and scored. It is distinct from sibling tools lookup_object and search_objects which focus on individual objects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for planning a session given location and date, but does not explicitly state when not to use or compare with sibling tools. Context is clear, but exclusions are absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search and filter the celestial object catalog by type, constellation, magnitude, angular size, or catalog membership. Returns a formatted table of matching objects sorted by brightness.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | Object type code (e.g. G=Galaxy, PN=Planetary Nebula, OCl=Open Cluster) | |
| limit | No | Maximum number of results (default 20, max 100) | |
| catalog | No | Filter by catalog membership | |
| minSize | No | Minimum angular size in arcminutes | |
| maxMagnitude | No | Maximum (faintest) visual magnitude to include | |
| minMagnitude | No | Minimum (brightest) visual magnitude to include | |
| constellation | No | IAU constellation abbreviation (e.g. Ori, And, Sgr) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reveals that the tool returns a formatted table sorted by brightness, which is a behavioral detail. However, it does not mention side effects, permissions, or if it's read-only. With no annotations, the description carries the burden and provides only basic behavior information.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose and key filters, followed by output summary. Every word is functional; no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core functionality and output format adequately for a search tool of moderate complexity. However, it could elaborate on the return table structure or catalog scope, especially since there is no output schema. The tool has 7 parameters and no annotations, so slightly more detail would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description adds no new meaning beyond what is already documented in the parameter descriptions. The description restates filter criteria but does not clarify format or units beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches and filters a celestial object catalog with specific criteria (type, constellation, magnitude, etc.) and returns a formatted table. While it doesn't explicitly differentiate from siblings like lookup_object, the 'table of matching objects' implies a multi-result set, which distinguishes it from a single-object lookup.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (lookup_object, plan_session) or when not to use it. The description implies it's for broad searches, but lacks explicit context for choosing among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0lookup_objectplan_sessionsearch_objectsScored across 3 tools
Each tool serves a distinct purpose: looking up a specific object, planning a session, and searching the catalog. No overlap or ambiguity.
All tool names follow a consistent verb_noun pattern (lookup_object, plan_session, search_objects) with underscores, making them predictable.
Three tools is well-scoped for a specialized astronomy server, covering the essential tasks without unnecessary complexity.
The set covers core use cases: object lookup, session planning, and catalog search. A minor gap might be detailed ephemeris calculations, but the surface is complete for its stated purpose.
Observational astronomy in one place
Live space data for AI agents - rocket launches, ISS passes, launch news. Free, no auth.
Offline observational astronomy: positions, rise/set, moon phases, eclipses, and seasons.
Real astrology for AI agents: cosmic weather, synastry, timing, astrocartography, and divination.