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]}
}
Integrate with Metabase to query databases and visualize data. Requires Metabase URL and API key for authentication.
Universal database MCP server supporting multiple database types including PostgreSQL, Redshift, CockroachDB, MySQL, RDS MySQL, Microsoft SQL Server, BigQuery, Oracle DB, and SQLite
Connect to any relational database, and be able to get valid SQL, and ask questions like what does a certain column prefix mean.
Server implementation for Google BigQuery integration that enables direct BigQuery database access and querying capabilities
Provides access to Jewish texts from the Sefaria library.
Securely access BigQuery datasets with intelligent caching, schema tracking, and query analytics via Supabase integration.
A production-ready MCP server for Customer Relationship Management (CRM) functionality, built with TypeScript and SQLite.
Connect AI tools with Pinecone projects to search, configure indexes, generate code, and manage data.
Interact with the microCMS headless CMS API, enabling AI assistants to manage content.
Stock market API made for AI agents