Astro

Astro MCP provides a modular server that unifies access to multiple astronomical datasets. It lets you ask for data in natural language or structured requests and receive processing-ready results, cross-survey if needed, with automatic data handling and format conversions.

How to use

You connect your MCP client to the Astro MCP server to perform cross-survey queries, retrieve spectra, catalogs, and images, and save results locally. Start with a basic search or a simple astroquery query to see how the system translates your natural language or structured input into multi-source data retrieval. You can search by coordinates, object names, redshift ranges, and more, then inspect, convert, or save the results in standard formats like CSV or FITS. The system automatically handles coordinate conversions, data provenance, and file organization so you can focus on analysis.

How to install

Prerequisites: you need Python and a suitable environment manager. The setup uses a dedicated Python environment to isolate dependencies.

# Clone the project
git clone https://github.com/SandyYuan/astro_mcp.git
cd astro_mcp

# Create and activate an isolated Python environment
conda create -n mcp python=3.11
conda activate mcp

# Install core dependencies
pip install -r requirements.txt

# Install astronomical libraries for full functionality
pip install sparclclient datalab astropy astroquery

Additional configuration and usage notes

Configure your MCP client to launch the server locally with the provided Python interpreter from your conda environment. You will run the server as a stdio-based local process so your client communicates through standard input/output.

{
  "mcpServers": {
    "astro_mcp_cursor": {
      "type": "stdio",
      "name": "astro_mcp_cursor",
      "command": "/path/to/conda/envs/mcp/bin/python",
      "args": ["/path/to/astro_mcp/server.py"],
      "cwd": "/path/to/astro_mcp",
      "env": {}
    },
    "astro_mcp_claude": {
      "type": "stdio",
      "name": "astro_mcp_claude",
      "command": "/path/to/conda/envs/mcp/bin/python",
      "args": ["/path/to/astro_mcp/server.py"],
      "cwd": "/path/to/astro_mcp",
      "env": {}
    }
  }
}

Troubleshooting

If the server won’t start, verify you are using the correct Python environment and that the server script path exists. Activate the environment, check Python version, and try launching the server manually.

If MCP connections fail, confirm the working directory points to the Astro MCP project and that dependencies are installed in the active environment.

Missing astronomical data? Install optional dependencies to unlock full functionality and service coverage.

Available tools

search_objects

Find astronomical objects through the server for DESI data access and catalogs across surveys.

astroquery_query

Run queries across 40+ astroquery services in a unified interface and return results in standard formats.

get_spectrum_by_id

Retrieve spectral data by identifier from DESI SPARCL or associated datasets.

list_astroquery_services

Discover available astroquery services and their capabilities.

preview_data

Inspect saved data files and analyze their structure without fully loading them.

list_files

Show all stored data across sources and manage the registry.

file_statistics

Provide storage usage statistics and data organization information.

convert_to_fits

Convert catalogs, spectra, or images to FITS format for astronomy software compatibility.