NASA APOD FastAPI + MCP Demo

Production-style mini project with three parts:

1. FastAPI backend that proxies NASA APOD.

2. MCP stdio server exposing nasa_apod_get.

3. Minimal responsive UI served by FastAPI.

Project Structure

app/
  api/
  models/
  services/
  static/
mcp_server/
tests/

Related MCP server: NASA APOD MCP Server

Prerequisites

• Python 3.11+

Install

python3 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -r requirements.txt
cp .env.example .env

Set NASA_API_KEY in .env for production. DEMO_KEY is fallback for local development only.

Run API

make run-api
# or
python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Health check:

curl http://127.0.0.1:8000/health

APOD:

curl "http://127.0.0.1:8000/api/nasa/apod?date=2026-03-25"

UI:

• Open http://127.0.0.1:8000/

Run MCP Server (stdio)

make run-mcp
# or
python -m mcp_server.server

Connect MCP in OpenCode

Use this snippet in OpenCode MCP config:

{
  "mcpServers": {
    "nasa-apod": {
      "command": "python",
      "args": ["-m", "mcp_server.server"],
      "cwd": "/absolute/path/to/nasa-mcp-demo",
      "env": {
        "NASA_API_KEY": "DEMO_KEY"
      }
    }
  }
}

Then invoke tool:

nasa_apod_get(date="2026-03-25")

Expected output format:

{
  "date": "2026-03-25",
  "title": "...",
  "explanation": "...",
  "url": "...",
  "hdurl": "...",
  "media_type": "image",
  "copyright": "..."
}

Testing

make test
# or
pytest -q

Includes:

• Unit tests for date validation, normalization, and error mapping.

• API integration tests for health and APOD success/failure paths.

• MCP tests for tool registration and call behavior.

Optional Live NASA Test

Current tests use httpx.MockTransport for stability. Add live tests guarded by env flag if needed.

Troubleshooting

• ModuleNotFoundError: ensure virtual environment is active and dependencies installed.

• 502 from /api/nasa/apod: verify NASA_API_KEY, network, and NASA API status.

• 504 from /api/nasa/apod: upstream timeout; retry later or increase NASA_TIMEOUT_SECONDS.

• MCP tool not discoverable: confirm command runs in project root and MCP config cwd is correct.

mcp-nasa

mcp-nasa

mcp-nasa