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

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) ✅

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

Authors

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

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

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:

   • Windows: Open File Explorer and go to %APPDATA%\Claude\
   • macOS: ~/Library/Application Support/Claude/

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:
   • "Search ALMA for observations of M87"
   • "Find high-resolution ALMA data with resolution under 0.5 arcseconds"
   • "What are ALMA's frequency bands?"

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"

License

MIT License - See LICENSE for details.