A modular server providing unified access to multiple astronomical datasets, including astroquery services and DESI data sources.
A modular Model Context Protocol (MCP) server that provides unified access to multiple astronomical datasets through a clean, extensible architecture.
This MCP server aims to transform big-data astronomy from a software engineering problem into a natural language conversation. Instead of spending months learning astroquery APIs, researchers simply ask for what they need and get clean, processed analysis-ready data products.
One expert solves the complexity once; thousands of scientists benefit forever. A student with little programming experience can now perform the same multi-survey analysis as an expert astronomer using nothing but natural language and an AI assistant.
This isn't just about astronomy—it's a template for democratizing all of science. Every field has brilliant researchers spending 80% of their time on data wrangling instead of discovery. By removing that bottleneck, we accelerate the pace of scientific progress itself.
The result: AI scientists that can seamlessly access and cross-match data from dozens of astronomical surveys, enabling discoveries that would have taken months of setup to attempt just a few years ago.
# Clone the repository
git clone https://github.com/SandyYuan/astro_mcp.git
cd astro_mcp
# Create a dedicated conda environment with Python 3.11+
conda create -n mcp python=3.11
conda activate mcp
# Install dependencies
pip install -r requirements.txt
# Install astronomical libraries for full functionality
pip install sparclclient datalab astropy astroquery
# Test basic functionality
python test_server.py
# Test with a simple query (optional)
python -c "
import asyncio
from server import astro_server
async def test():
result = astro_server.get_global_statistics()
print('✅ Server working:', result['total_files'], 'files in registry')
services = astro_server.list_astroquery_services()
print(f'✅ Astroquery: {len(services)} services discovered')
asyncio.run(test())
"
Add this configuration to your Cursor MCP settings:
{
"mcpServers": {
"astro-mcp": {
"command": "/path/to/conda/envs/mcp/bin/python",
"args": ["/path/to/astro_mcp/server.py"],
"cwd": "/path/to/astro_mcp",
"env": {}
}
}
}
To find your conda Python path:
conda activate mcp
which python
# Copy this path for the "command" field above
Edit your Claude Desktop MCP configuration file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"astro-mcp": {
"command": "/path/to/conda/envs/mcp/bin/python",
"args": ["/path/to/astro_mcp/server.py"],
"cwd": "/path/to/astro_mcp",
"env": {}
}
}
}
Server won't start:
# Check Python environment
conda activate mcp
python --version # Should be 3.11+
# Test server manually
python server.py
# Should start without errors
MCP connection issues:
cwd) points to the astro_mcp folderMissing astronomical data:
# Install optional dependencies for full functionality
conda activate mcp
pip install sparclclient datalab astropy astroquery h5py
Once configured, you can ask natural language questions about astronomical data:
The server will automatically:
astro_mcp/
├── server.py # Main MCP server entry point
├── data_sources/ # Modular data source implementations
│ ├── __init__.py
│ ├── base.py # Base class for all data sources
│ ├── desi.py # DESI survey data access
│ ├── astroquery_universal.py # Universal astroquery wrapper
│ └── astroquery_metadata.py # Service metadata and capabilities
├── data_io/ # File handling and conversion
│ ├── __init__.py
│ ├── preview.py # Data preview and structure analysis
│ └── fits_converter.py # FITS format conversion
├── tests/ # Test suite
├── examples/ # Usage examples
└── requirements.txt # Project dependencies
Quick Start: For Cursor & Claude Desktop integration, see the Quick Setup section above.
# Clone the repository
git clone https://github.com/SandyYuan/astro_mcp.git
cd astro_mcp
# Create and activate environment
conda create -n mcp python=3.11
conda activate mcp
# Install core dependencies
pip install -r requirements.txt
# Install astronomical libraries
pip install sparclclient datalab astropy astroquery
# Optional: Install development dependencies
pip install pytest coverage
# Test the server components
python test_server.py
# Check available astroquery services
python -c "
import asyncio
from server import astro_server
async def show_services():
services = astro_server.list_astroquery_services()
print(f'✅ Discovered {len(services)} astroquery services')
for service in services[:5]: # Show first 5
print(f' - {service["full_name"]} ({service["service"]})')
asyncio.run(show_services())
"
python server.py
The server provides these main tools:
Data Access:
search_objects - Find astronomical objects (DESI)astroquery_query - Universal queries across 40+ astronomical servicesget_spectrum_by_id - Retrieve detailed spectral data (DESI)Service Discovery:
list_astroquery_services - Show all available astronomical databasesget_astroquery_service_details - Detailed service informationsearch_astroquery_services - Find services by criteriaFile Management:
preview_data - Inspect saved files with structure analysislist_files - Manage saved data across all sourcesfile_statistics - Storage usage and organization infoconvert_to_fits - Convert data to FITS format# Get object coordinates from SIMBAD
astroquery_query(
service_name="simbad",
object_name="Betelgeuse"
)
# Search SDSS for galaxies with SQL
astroquery_query(
service_name="sdss",
query_type="query_sql",
sql="SELECT TOP 10 ra, dec, z FROM SpecObj WHERE class='GALAXY' AND z BETWEEN 0.1 AND 0.3"
)
# Search VizieR catalogs
astroquery_query(
service_name="vizier",
ra=10.68,
dec=41.27,
radius=0.1
)
# Convert results to FITS
convert_to_fits(
identifier="search_results.csv",
data_type="catalog"
)
Status: ✅ Fully Implemented
Status: ✅ Fully Implemented
Major Services Available:
Capabilities:
Required Dependencies:
pip install astroquery astropy
# data_sources/my_survey.py
from .base import BaseDataSource
class MySurveyDataSource(BaseDataSource):
def __init__(self, base_dir=None):
super().__init__(base_dir=base_dir, source_name="my_survey")
# Initialize survey-specific clients
def search_objects(self, **kwargs):
# Implement survey-specific search
pass
# server.py
from data_sources import MySurveyDataSource
class AstroMCPServer:
def __init__(self, base_dir=None):
# ... existing code ...
self.my_survey = MySurveyDataSource(base_dir=base_dir)
The astroquery integration automatically discovers new services. To add custom metadata:
# data_sources/astroquery_metadata.py
ASTROQUERY_SERVICE_INFO = {
"my_service": {
"full_name": "My Custom Service",
"description": "Custom astronomical database",
"data_types": ["catalogs", "images"],
"wavelength_coverage": "optical",
"object_types": ["stars", "galaxies"],
"requires_auth": False,
"example_queries": [
{
"description": "Search by object name",
"query": "astroquery_query(service_name='my_service', object_name='M31')"
}
]
}
}
Files are automatically organized by data source with comprehensive metadata:
~/astro_mcp_data/
├── file_registry.json # Global file registry with metadata
├── desi/ # DESI-specific files
│ ├── desi_search_*.json # Search results
│ ├── spectrum_*.json # Spectral data
│ └── *.fits # FITS conversions
└── astroquery/ # Astroquery results
├── astroquery_simbad_*.csv # SIMBAD queries
├── astroquery_sdss_*.csv # SDSS results
├── astroquery_vizier_*.csv # VizieR catalogs
└── *.fits # FITS conversions
# Run all tests
pytest
# Test specific modules
pytest tests/test_desi.py
pytest tests/test_astroquery.py
# Test with coverage
pytest --cov=data_sources tests/
git checkout -b feature/new-capability)mcp>=1.0.0 - Model Context Protocol frameworkpandas>=2.0.0 - Data manipulationnumpy>=1.24.0 - Numerical computingastroquery>=0.4.6 - Universal astronomical database accessastropy>=5.0.0 - FITS files and astronomical calculationssparclclient>=1.0.0 - DESI SPARCL accessdatalab>=2.20.0 - NOAO Data Lab queriesh5py>=3.8.0 - HDF5 file supportpytest>=7.0.0 - Testing framework[Specify your license here]
If you use this software in your research, please cite:
@software{astro_mcp,
title={Astro MCP: Universal Astronomical Data Access for AI Agents},
author={[Your Name]},
year={2024},
url={[Repository URL]}
}
MCP server acting as an interface to the Frankfurter API for currency exchange data.
Provides tools and resources for coding agents to interact with the Gel database, including automatic project configuration for query builders and ORMs.
Access Dungeons & Dragons 5th Edition content, including spells, classes, and monsters, via the Open5e API.
A TypeScript and SQLite-based server enabling AI to remember personal data for personalized communication.
An MCP server that provides tools to interact with Powerdrill datasets, enabling smart AI data analysis and insights.
Access Crunchbase data for business information and insights. Requires a Crunchbase API key.
A Kotlin-based MCP server for interacting with PostgreSQL databases.
Allows LLMs to directly interact with a YugabyteDB database.
Interface with Biomart, a biological data query tool, using the pybiomart Python package.
Allows AI to interact with Microsoft Access databases, supporting data import and export via CSV files.