nasa-exoplanet-mcp 0.1.0

MCP server for querying NASA's Exoplanet Archive

NASA Exoplanet Archive MCP Server

An MCP server that gives AI assistants direct access to NASA's Exoplanet Archive — the authoritative database of every confirmed exoplanet, candidate planet, and host star. Built on the archive's TAP (Table Access Protocol) service with full ADQL query support.

What can you do with it?

Once connected, you can ask your AI assistant questions like:

• "Find rocky planets in the habitable zone within 50 parsecs of Earth"
• "What do we know about the TRAPPIST-1 system?"
• "How many exoplanets has TESS discovered? Break it down by year."
• "Show me planets with atmospheric spectroscopy data available"
• "Compare the orbital parameters of all planets around Kepler-90"
• "What's the mass-radius distribution of transiting planets discovered after 2020?"

The server handles everything — name resolution, query construction, pagination, error handling — so the AI can focus on answering the question.

Available Tools

Tool	Description
search_planets	Search confirmed exoplanets with flexible filters (radius, mass, temperature, distance, discovery method, facility, year, and more). The primary tool for most questions.
get_planet	Get comprehensive details for a single planet — orbital, physical, stellar, and discovery properties with uncertainties.
resolve_name	Translate any name or catalog ID (TIC, KOI, Gaia, 2MASS, HD, HIP) to the canonical archive name. Handles common issues like missing spaces in planet names.
list_tables	Discover all 40+ tables in the archive — confirmed planets, TESS candidates, Kepler KOIs, transit spectroscopy, microlensing, time series, and more.
list_columns	Explore the 300+ available columns for any table, filterable by category (orbital, physical, stellar, discovery, system, photometry).
run_query	Execute raw ADQL queries for full flexibility — aggregations, JOINs, spatial/cone searches, or querying any table in the archive.

Quick Start

Prerequisites

• Python 3.10+
• uv (recommended) or pip

Install

git clone https://github.com/saikrmet/nasa-exoplanet-mcp.git
cd nasa-exoplanet-mcp
uv venv && uv pip install -e .

Run

Local (stdio) — for Claude Desktop, Claude Code, or any local MCP client:

nasa-exoplanet-mcp

Remote (HTTP) — for hosted deployments or remote MCP clients:

nasa-exoplanet-mcp serve
nasa-exoplanet-mcp serve --port 9000
nasa-exoplanet-mcp serve --host 127.0.0.1 --port 9000

The server will be available at http://your-host:8000/mcp.

Adding to your MCP client

Requires uv to be installed.

Claude Desktop

Open your claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "nasa-exoplanet": {
      "command": "uvx",
      "args": ["nasa-exoplanet-mcp"]
    }
  }
}

Restart Claude Desktop — the 6 exoplanet tools appear automatically.

Claude Code

claude mcp add nasa-exoplanet -- uvx nasa-exoplanet-mcp

Other MCP clients (Cursor, Windsurf, etc.)

Any client that supports stdio MCP servers works. Use uvx as the command and ["nasa-exoplanet-mcp"] as the args.

Remote deployment

If you're hosting the server (e.g. as a web app), start it with the serve subcommand:

nasa-exoplanet-mcp serve
nasa-exoplanet-mcp serve --host 0.0.0.0 --port 8000

Then point your MCP client at the URL:

{
  "mcpServers": {
    "nasa-exoplanet": {
      "url": "http://your-host:8000/mcp"
    }
  }
}

Tool Details

search_planets

The primary tool for most exoplanet questions. All parameters are optional and combinable.

Parameter	Type	Description
name	string	Planet name (partial match)
hostname	string	Host star name — returns all planets in the system
discovery_method	string	Transit, Radial Velocity, Microlensing, Imaging, etc.
facility	string	Discovery facility (TESS, Kepler, etc., partial match)
min_radius / max_radius	float	Planet radius in Earth radii (Earth=1.0, Jupiter~11.2)
min_mass / max_mass	float	Planet mass in Earth masses (Earth=1.0, Jupiter~317.8)
min_period / max_period	float	Orbital period in days
min_temperature / max_temperature	float	Equilibrium temperature in K (habitable zone ~200-320K)
min_distance / max_distance	float	Distance in parsecs (1 pc ~ 3.26 light-years)
year_min / year_max	int	Discovery year
min_planets_in_system	int	For multi-planet systems (use 2+)
columns	list	Columns to return (defaults to curated set of 12)
order_by	string	Sort column, prefix with - for descending (e.g., sy_dist nearest, -pl_eqt hottest, -pl_bmasse most massive)
limit	int	Max results, 1-500 (default 25)
offset	int	Skip N results for pagination

get_planet

Returns comprehensive data for a single planet, organized into categories:

• Identity: name, host star, catalog IDs (TIC, Gaia, HD, HIP)
• Orbital: period, semi-major axis, eccentricity, inclination (with uncertainties)
• Physical: radius, mass, density, equilibrium temperature, insolation flux
• Transit: depth, duration, midpoint, impact parameter
• Stellar: spectral type, temperature, mass, radius, metallicity, age
• Discovery: method, year, facility, telescope, instrument
• System: number of planets/stars, distance, coordinates
• Data availability: counts of available spectra and observations

run_query

For queries that need full ADQL power. Examples:

-- Discovery statistics by year
SELECT disc_year, COUNT(*) AS n FROM pscomppars
WHERE disc_year IS NOT NULL GROUP BY disc_year ORDER BY disc_year DESC

-- Cone search: planets within 5 degrees of coordinates
SELECT pl_name, hostname, ra, dec, sy_dist FROM pscomppars
WHERE CONTAINS(POINT('ICRS',ra,dec), CIRCLE('ICRS',291.0,48.0,5.0))=1

-- TESS candidates with specific disposition
SELECT * FROM toi WHERE tfopwg_disp = 'PC' ORDER BY toi

-- Transit spectroscopy data for a planet
SELECT * FROM transitspec WHERE plntname = 'WASP-39 b'

-- Planets with both mass and radius measurements (for density studies)
SELECT pl_name, pl_rade, pl_bmasse, pl_dens FROM pscomppars
WHERE pl_rade IS NOT NULL AND pl_bmasse IS NOT NULL AND pl_dens IS NOT NULL

Data Source

This server queries the NASA Exoplanet Archive operated by IPAC at Caltech, under contract with NASA as part of the Exoplanet Exploration Program. The archive is the official NASA repository for exoplanet data and is updated weekly.

No API key is required. The archive is free and open to everyone.

Key tables accessible through this server:

Table	Contents	Rows
pscomppars	Confirmed planets (composite best values)	~6,300
ps	All published measurements (multiple per planet)	~39,900
stellarhosts	Host star properties	~47,600
toi	TESS candidate planets	~7,900
cumulative	Kepler Objects of Interest	~9,600
k2pandc	K2 planets and candidates	~4,000
ml	Microlensing planets	~880
transitspec	Transit spectroscopy (atmospheric)	~5,900
emissionspec	Emission spectroscopy	~2,400

Debugging

Use the MCP Inspector to test the server interactively:

npx @modelcontextprotocol/inspector uvx nasa-exoplanet-mcp

Server logs are written to stderr and won't interfere with the stdio transport.

Development

git clone https://github.com/saikrmet/nasa-exoplanet-mcp.git
cd nasa-exoplanet-mcp
uv venv && uv pip install -e ".[dev]"

# Run the server locally
nasa-exoplanet-mcp

# Open FastMCP dev inspector
mcp dev src/server.py:mcp

# Run tests
uv run pytest

# Lint
uv run ruff check src/

Testing

This project has three layers of tests:

Layer	Command	What it tests
Unit	pytest tests/test_unit.py	Query building, error parsing, validation. No network. Fast (<1s).
Integration	pytest tests/test_integration.py	Live calls to the NASA Exoplanet Archive. Verifies real data. ~2 min.
LLM scenarios	pytest -m llm	End-to-end: an LLM agent reads tool descriptions, picks tools, returns answers. ~7 min, opt-in.

The first two run without any setup. The LLM layer requires an API key.

Running the LLM scenario suite

These tests spin up an LLM agent that reads only the MCP tool descriptions, then verifies it correctly chooses tools and returns factually correct answers for 44 natural-language scenarios spanning 8 categories (simple lookup, filtered search, aggregation, multi-step queries, name resolution, error recovery, ambiguous questions, out-of-scope questions).

Install the LLM test dependencies:

uv pip install -e ".[llm]"

Configure your provider by creating a .env file at the project root (see .env.example). Supported providers:

# OpenAI
TEST_MODEL=openai:gpt-4o-mini
OPENAI_API_KEY=sk-...

# Anthropic
TEST_MODEL=anthropic:claude-haiku-4-5
ANTHROPIC_API_KEY=sk-ant-...

# Google Gemini
TEST_MODEL=google-gla:gemini-2.5-flash
GOOGLE_API_KEY=...

# Azure OpenAI
TEST_MODEL=azure:<your-deployment-name>
AZURE_OPENAI_API_KEY=...
AZURE_OPENAI_ENDPOINT=https://<resource>.cognitiveservices.azure.com
AZURE_OPENAI_API_VERSION=2025-04-01-preview

Run the suite:

pytest -m llm -v

If TEST_MODEL is not set, all LLM tests auto-skip — pytest still runs cleanly without them.

Adding new scenarios is straightforward — append a Scenario(...) entry to tests/llm/scenarios.py.

Project Structure

src/
  server.py            # FastMCP server instance and entry point
  client.py            # Async HTTP client for TAP and Alias APIs
  config.py            # Default columns, table metadata, valid enums
  errors.py            # Error types and TAP XML error parser
  tools/
    search.py          # search_planets
    planet.py          # get_planet
    names.py           # resolve_name
    schema.py          # list_tables, list_columns
    query.py           # run_query

License

MIT