Metadata-Version: 2.4
Name: nasa-exoplanet-mcp
Version: 0.1.0
Summary: MCP server for querying NASA's Exoplanet Archive
Project-URL: Repository, https://github.com/saikrmet/nasa-exoplanet-mcp
Author-email: Saikishore Mettupalli <saikrmet@gmail.com>
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: httpx<1,>=0.27.0
Requires-Dist: mcp[cli]<2,>=1.2.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: llm
Requires-Dist: pydantic-ai>=0.0.50; extra == 'llm'
Requires-Dist: python-dotenv>=1.0; extra == 'llm'
Description-Content-Type: text/markdown

# 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](https://docs.astral.sh/uv/) (recommended) or pip

### Install

```bash
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:

```bash
nasa-exoplanet-mcp
```

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

```bash
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](https://docs.astral.sh/uv/getting-started/installation/) 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`

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

Restart Claude Desktop — the 6 exoplanet tools appear automatically.

### Claude Code

```bash
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:

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

Then point your MCP client at the URL:

```json
{
  "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:

```sql
-- 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](https://exoplanetarchive.ipac.caltech.edu/) operated by [IPAC](https://www.ipac.caltech.edu/) at Caltech, under contract with NASA as part of the [Exoplanet Exploration Program](https://exoplanets.nasa.gov/). 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](https://modelcontextprotocol.io/docs/tools/inspector) to test the server interactively:

```bash
npx @modelcontextprotocol/inspector uvx nasa-exoplanet-mcp
```

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

## Development

```bash
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:

```bash
uv pip install -e ".[llm]"
```

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

```bash
# 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:

```bash
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
