NASA APOD FastAPI + MCP Demo
Production-style mini project with three parts:
- FastAPI backend that proxies NASA APOD.
- MCP stdio server exposing
nasa_apod_get. - Minimal responsive UI served by FastAPI.
Project Structure
app/
api/
models/
services/
static/
mcp_server/
tests/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 .envSet 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 8000Health check:
curl http://127.0.0.1:8000/healthAPOD:
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.serverConnect 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 -qIncludes:
- 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.502from/api/nasa/apod: verifyNASA_API_KEY, network, and NASA API status.504from/api/nasa/apod: upstream timeout; retry later or increaseNASA_TIMEOUT_SECONDS.- MCP tool not discoverable: confirm command runs in project root and MCP config
cwdis correct.
