ALMA MCP Server - Astronomical Data Access via Natural Language

A Model Context Protocol (MCP) server that provides comprehensive access to the ALMA (Atacama Large Millimeter/submillimeter Array) archive through a clean, extensible architecture.

Vision

This MCP server transforms ALMA archive queries from a software engineering problem into a natural language conversation. Instead of learning TAP/ADQL syntax and archive APIs, researchers simply ask for what they need and get clean, analysis-ready results.

The result: AI assistants that can seamlessly search ALMA data by target, position, frequency, resolution, or any custom criteria

Quick Setup for Claude Desktop

1. Clone/Copy and Setup Environment

> IMPORTANT: Change the paths below according to YOUR installation location!

# Clone the repository (or copy the ALMA_MCP folder)
git clone https://github.com/adamzacharia/ALMA_MCP.git
cd ALMA_MCP

# Create a dedicated conda environment with Python 3.11+
conda create -n alma_mcp python=3.11
conda activate alma_mcp

# Install dependencies
pip install -r requirements.txt

# Install astronomical libraries for full functionality
pip install fastmcp alminer pyvo astroquery astropy pandas

Alternative: Using venv instead of conda:

# Navigate to the ALMA_MCP folder
cd path/to/ALMA_MCP

# Create a dedicated venv environment
python -m venv venv
venv\Scripts\activate  # Windows
# source venv/bin/activate  # Mac/Linux

# Install dependencies
pip install -r requirements.txt

2. Test the Server

# Test basic functionality
python test_server.py

# Quick test (optional)
python -c "
from server import get_alma_info, ALMINER_AVAILABLE, PYVO_AVAILABLE
print(' Server loads successfully')
print(f' alminer available: {ALMINER_AVAILABLE}')
print(f' pyvo available: {PYVO_AVAILABLE}')
"

3. Configure Claude Desktop

Find and edit the Claude Desktop MCP configuration file:

1. Navigate to your Claude Desktop AppData folder:

2. add the 'claude_desktop_config.json' or add the below to your 'config.json' file

3. Add the following configuration to the file:

> IMPORTANT: Change the path below according to YOUR installation location!

{
  "mcpServers": {
    "alma": {
      "command": "python",
      "args": ["c:/Users/Asus/Desktop/Quasar-main/ALMA_MCP/server.py"]
    }
  }
}

> Note: Use forward slashes `/` in paths even on Windows.

Using a Custom Environment (Conda or venv)

If you installed the dependencies in a conda environment or venv, you MUST specify the full path to that environment's Python executable. Otherwise the system won't find the installed packages!

For Conda environment:

{
  "mcpServers": {
    "alma": {
      "command": "C:/Users/YourName/anaconda3/envs/alma_mcp/python.exe",
      "args": ["c:/path/to/ALMA_MCP/server.py"],
      "cwd": "c:/path/to/ALMA_MCP",
      "env": {}
    }
  }
}

To find your conda environment's Python path, run:

conda activate alma_mcp
where python    # Windows
which python    # Mac/Linux

For venv:

{
  "mcpServers": {
    "alma": {
      "command": "c:/path/to/ALMA_MCP/venv/Scripts/python.exe",
      "args": ["c:/path/to/ALMA_MCP/server.py"],
      "cwd": "c:/path/to/ALMA_MCP",
      "env": {}
    }
  }
}

4. Restart and Test

1. Quit Claude Desktop completely (right-click system tray → Quit)

2. Check Task Manager - If Claude is still running in the background, end the task

3. Reopen Claude Desktop

4. Test with a query like:

5. Troubleshooting

Server won't start:

# Check Python environment
python --version  # Should be 3.10+

# Test server manually
python server.py
# Should start without errors

MCP connection issues:

• Verify the Python path in your config is correct
• Ensure all dependencies are installed
• Check that `server.py` exists at the specified path

Missing dependencies:

pip install fastmcp alminer pyvo astroquery astropy pandas

Usage Examples

Once configured, you can ask natural language questions about ALMA data:

Basic Searches

• "Find observations of Orion KL"
• "Search ALMA for M87 within 1 arcminute"
• "What ALMA data exists for NGC 1234?"

Position-Based Searches

• "Search ALMA at RA=83.6, Dec=-5.4"
• "Find observations near the Galactic Center"
• "Cone search at coordinates 150.5, 2.2 with 5 arcmin radius"

Frequency Searches

• "Find ALMA data between 230 and 250 GHz"
• "Search for Band 6 observations"
• "What observations cover the CO(2-1) line at 230.5 GHz?"

Resolution Searches

• "Find high-resolution data with resolution under 0.1 arcseconds"
• "Search for ALMA observations better than 0.5 arcsec resolution"

Proposal/PI Searches

• "Find ALMA proposals by Adele Plunket"
• "Get data for proposal 2023.1.00001.S"
• "Search for galaxy evolution proposals"

Spectral Line Coverage

• "Do any M87 observations cover the CO(2-1) line?"
• "Check if Orion data covers HCN(1-0) at 88.6 GHz"
• "Find observations that cover 115 GHz for a source at z=0.5"

Custom SQL Queries

• "Run this SQL: SELECT target_name, band_list FROM ivoa.obscore WHERE target_name LIKE '%M87%'"
• "Query ALMA for all Band 7 observations from 2023"

ALMA Information

• "What are ALMA's frequency bands?"
• "List common spectral lines in the mm range"
• "What science categories does ALMA support?"

Bibliography & Publication Searches

• "Find ALMA observations published in Nature"
• "Search for data used in papers by Smith published in 2023"
• "What ALMA data has the bibcode 2017ApJ...834..140R"

Science Keyword Searches

• "Find all ALMA observations tagged with 'Quasars'"
• "Search for Sub-mm Galaxies (SMG) observations"
• "What observations are categorized under 'Active Galactic Nuclei'?"

Data Type Searches

• "Find all spectral cubes for M87"
• "Search for continuum images tagged with Exoplanets"
• "Show me spectral line observations in Band 6"

Abstract Searches

• "Find proposals mentioning black holes in their abstract"
• "Search for observations from proposals about star formation"
• "What proposals mention the cosmic microwave background?"

Sensitivity Searches

• "Find observations with continuum sensitivity better than 0.1 mJy/beam"
• "Search for deep ALMA observations under 0.05 mJy sensitivity"

Batch Multi-Source Queries

• "Check if ALMA has observed M31, M51, M82, and NGC 1068"
• "Query ALMA for these sources: Cen A, M83, and NGC 1234"

Using with Other LLMs and Frameworks

LangChain Integration

You can use this MCP server with LangChain using the `langchain-mcp-adapters` package:

pip install langchain-mcp-adapters

from langchain_mcp_adapters.client import MCPClient
from langchain_openai import ChatOpenAI

# Connect to the MCP server
client = MCPClient(
    command="python",
    args=["path/to/ALMA_MCP/server.py"]
)

# Get tools from MCP server
tools = client.get_tools()

# Use with any LangChain-compatible LLM
llm = ChatOpenAI(model="gpt-4")
llm_with_tools = llm.bind_tools(tools)

Open Source LLMs

For open source LLMs (Ollama, LMStudio, etc.), you can:

1. Use MCP-compatible clients: Some open source projects like MCP CLI support connecting MCP servers to local LLMs.

2. Direct function calling: Import the server functions directly in your Python code:

from server import search_alma_by_target, search_alma_by_position, get_alma_info

# Use tools directly
result = search_alma_by_target("M87", search_radius_arcmin=5.0)
print(result)

# Get ALMA reference info
info = get_alma_info()
print(info)

3. Build a REST API: Wrap the MCP tools in a FastAPI/Flask server for any LLM that supports function calling via HTTP.

Architecture

ALMA_MCP/
├── server.py           # Main MCP server with 16 tools
├── requirements.txt    # Python dependencies
├── test_server.py      # Test suite
└── README.md           # This file

Features

ALMA Archive Access

• Target Search: Resolve object names via SIMBAD and search ALMA
• Position Search: Cone search by RA/Dec coordinates
• Proposal Search: Find by PI name, proposal ID, or science category
• Frequency Search: Query by frequency range (GHz)
• Resolution Search: Filter by angular resolution (arcsec)
• Custom SQL: Run any ADQL query against ALMA TAP

Core Query Tools (8 original)

Extended Query Tools (8 new - from ALMA notebooks)

Multi-Backend Support

• alminer: Advanced ALMA queries with spectral line tools
• pyvo: Direct TAP/ADQL access to ALMA archive
• astroquery: SIMBAD name resolution

Dependencies

Core Requirements

fastmcp>=2.0.0      # MCP framework
pandas>=1.5.0       # Data manipulation

Astronomical Libraries

alminer>=0.2.0      # Advanced ALMA queries
pyvo>=1.4.0         # TAP/ADQL access
astroquery>=0.4.0   # SIMBAD, VizieR, etc.
astropy>=5.0.0      # Astronomical utilities

Roadmap

Current (v1.0) ✅

• [x] ALMA target name search with SIMBAD resolution
• [x] Position-based cone search
• [x] Frequency range search
• [x] Angular resolution filtering
• [x] Proposal/PI search
• [x] Spectral line coverage check
• [x] Custom SQL/TAP queries
• [x] ALMA info and band reference
• [x] Source name search (PI-specified names, exact/partial)
• [x] Bibliography/publication search (bibcode, journal, author, year)
• [x] Member OUS ID search (dataset identifier)
• [x] Data type filtering (cubes vs images)
• [x] Science keyword search with filters
• [x] Abstract full-text search (proposal and publication)
• [x] Sensitivity-based search (continuum or line)
• [x] Batch multi-source queries

Planned (v2.0)

• [ ] VLA archive integration
• [ ] GBT archive integration
• [ ] Result caching for faster queries
• [ ] FITS file download support
• [ ] Cross-archive object matching (ALMA + VLA + optical)
• [ ] Visualization tools (sky plots, spectra)
• [ ] Data download workflow

Moving to Standalone Location

This folder is designed to be portable. To move it:

1. Copy the entire `ALMA_MCP/` folder to your desired location

2. Update the path in `config.json`

3. Restart Claude Desktop

Contributing

1. Fork the repository

2. Create a feature branch (`git checkout -b feature/vla-support`)

3. Add your data source following existing patterns

4. Write tests for new functionality

5. Submit a pull request

Authors

• Adam Zacharia Anil - Lead Developer
• Adele Plunkett - Scientific Advisor

Acknowledgments

Special thanks to:

• Adele Plunkett - For valuable guidance and advice throughout this project
• NRAO (National Radio Astronomy Observatory) - For supporting astronomical research and data access
• Brian Mason - For technical expertise and support
• Cosmic AI / Stella Offner - For inspiration in applying AI to astronomical research

License

MIT License - See LICENSE for details.

Citation

If you use this software in your research, please cite:

@software{alma_mcp,
  title={ALMA MCP Server: Astronomical Data Access for AI Agents},
  author={Adam Zacharia Anil and Adele Plunkett},
  year={2025},
  url={https://github.com/adamzacharia/ALMA_MCP}
}

Support

• Issues: GitHub Issues
• Documentation: This README and inline code comments
• Discussions: GitHub Discussions