NASA Images MCP Server
A project to search NASA's image library using an MCP server and display images in an interactive UI.
π Features:
- Dual Transport Support: Supports both stdio and Streamable HTTP transport
- Image Search: Search by keywords using NASA's Images API
- Interactive UI: Beautiful image viewer using MCP Apps Pattern
- Image Navigation: Display search results sequentially
- Session Management: Stateful session management

Requirements
- Node.js 18 or higher
- npm or yarn
- NASA API Key (get free at nasa.gov/api)
Installation
- Clone the repository:
cd nasa-images-mcp-server
- Install dependencies:
- Set up environment variables:
Edit the .env file to configure your NASA API key:
NASA_API_KEY=your_api_key_here
PORT=3000
- Build:
Getting a NASA API Key
- Visit https://api.nasa.gov/
- Enter your name and email address in the form
- The API key will be sent to your email immediately
- Add it to your
.env file
Rate Limits:
- DEMO_KEY: 30 requests/hour, 50 requests/day
- Registered key: 1000 requests/hour
Usage
stdio Mode (Recommended for MCP Clients like Claude Desktop)
In stdio mode, the server communicates via stdin/stdout β no HTTP server is started. Logs are written to stderr.
Run with npx (no installation required)
npx @kaitoy/nasa-images-mcp-server --stdio
Run from local build
Pass the --stdio flag to use stdio transport:
node build/index.js --stdio
Claude Desktop Configuration
Using npx (recommended):
{
"mcpServers": {
"nasa-images": {
"command": "npx",
"args": ["-y", "@kaitoy/nasa-images-mcp-server", "--stdio"],
"env": {
"NASA_API_KEY": "your_api_key_here"
}
}
}
}
Using local build:
{
"mcpServers": {
"nasa-images": {
"command": "node",
"args": ["/path/to/nasa-images-mcp-server/build/index.js", "--stdio"],
"env": {
"NASA_API_KEY": "your_api_key_here"
}
}
}
}
HTTP Server Mode
The server will start at http://localhost:3000.
Start on a Different Port
About Transports
stdio Transport
Suitable for local MCP clients (e.g., Claude Desktop) that launch the server as a subprocess.
- Communicates via stdin/stdout
- Single session per process
- No network configuration required
Streamable HTTP Transport
The latest MCP HTTP transport protocol, suitable for remote or multi-client scenarios.
Key Features:
- β
Stateful Sessions: Issues a unique session ID for each client
- β
SSE Support: Supports push notifications from the server via Server-Sent Events
- β
JSON-RPC over HTTP: Communication via standard HTTP request/response
- β
Session Management: Automatic session lifecycle management
Integration with MCP Clients
Connecting with MCP Inspector (HTTP mode)
You can test the server using MCP Inspector:
npx @modelcontextprotocol/inspector http://localhost:3000/mcp
Connecting with MCP Inspector (stdio mode)
npx @modelcontextprotocol/inspector node /path/to/nasa-images-mcp-server/build/index.js --stdio
Using with Custom MCP Clients
Steps to connect from a custom client:
- Initialize Request (POST /mcp):
curl -X POST http://localhost:3000/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2024-11-05",
"capabilities": {},
"clientInfo": {
"name": "my-client",
"version": "1.0.0"
}
}
}'
The response headers will include mcp-session-id.
- Subsequent Requests:
curl -X POST http://localhost:3000/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-H "mcp-session-id: <your-session-id>" \
-d '{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/list"
}'
- SSE Stream (GET /mcp):
curl -X GET "http://localhost:3000/mcp" \
-H "mcp-session-id: <your-session-id>" \
-H "Accept: text/event-stream"
Endpoints
| Endpoint | Method | Description |
|---|
/ | GET | Server information and endpoint list |
/health | GET | Health check (includes active session count) |
/mcp | POST | JSON-RPC requests (initialization, tool calls, etc.) |
/mcp | GET | SSE stream (for server notifications) |
/mcp | DELETE | Close session |
Available Tools
1. search_nasa_images
Search NASA's image library.
Parameters:
query (string, required): Search query (e.g., "apollo 11", "mars rover")
Usage Example (JSON-RPC):
{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "search_nasa_images",
"arguments": {
"query": "apollo 11 moon landing"
}
}
}
2. get_next_image
Display the next image from the current search results.
Parameters:
None
Usage Example (JSON-RPC):
{
"jsonrpc": "2.0",
"id": 4,
"method": "tools/call",
"params": {
"name": "get_next_image",
"arguments": {}
}
}
Available Resources
nasa-image://current
Get the URL of the currently displayed image.
MIME Type: text/uri-list
ui://nasa-images/viewer
HTML UI resource for the image viewer.
MIME Type: text/html;profile=mcp-app
Architecture
stdio Mode
βββββββββββββββββββββββββββββββββββββββββββββββ
β MCP Client (Claude Desktop, etc.) β
β β stdin/stdout β
βββββββββββββββββββββΌββββββββββββββββββββββββββ
β
βββββββββββββββββββββΌββββββββββββββββββββββββββ
β NASA Images MCP Server β
β ββββββββββββββββββ΄βββββββββββββββββββββββ β
β β StdioServerTransport β β
β βββββββββββββββββββββββββββββββββββββββββ β
β βββββββββββββββββββββββββββββββββββββββββ β
β β McpServer (MCP Apps Pattern) β β
β β - registerAppTool(search_nasa...) β β
β β - registerAppTool(get_next_image) β β
β β - registerAppResource(viewer UI) β β
β β - registerResource(image URL) β β
β βββββββββββββββββββββββββββββββββββββββββ β
β βββββββββββββββββββββββββββββββββββββββββ β
β β Session Manager β β
β β - Manage search state per user β β
β βββββββββββββββββββββββββββββββββββββββββ β
β βββββββββββββββββββββββββββββββββββββββββ β
β β NASA API Client β β
β β - Image search β β
β β - Image URL retrieval β β
β βββββββββββββββββββββββββββββββββββββββββ β
βββββββββββββββββββββΌββββββββββββββββββββββββββ
β HTTPS
βββββββββββββββββββββΌββββββββββββββββββββββββββ
β NASA Images API β
β https://images-api.nasa.gov/search β
βββββββββββββββββββββββββββββββββββββββββββββββ
HTTP Mode
βββββββββββββββββββββββββββββββββββββββββββββββ
β MCP Client (Inspector, Custom App) β
β β
β ββββββββββββββββββββββββββββββββββββββββββ β
β β HTTP Client β β
β β - POST /mcp (JSON-RPC requests) β β
β β - GET /mcp (SSE stream) β β
β ββββββββββββββββββββββββββββββββββββββββββ β
β β β
βββββββββββββββββββββΌββββββββββββββββββββββββββ
β HTTP/SSE
βββββββββββββββββββββΌββββββββββββββββββββββββββ
β NASA Images MCP Server (Express) β
β ββββββββββββββββββ΄βββββββββββββββββββββββ β
β β StreamableHTTPServerTransport β β
β β - Session management β β
β β - JSON-RPC over HTTP β β
β β - SSE for notifications β β
β βββββββββββββββββββββββββββββββββββββββββ β
β βββββββββββββββββββββββββββββββββββββββββ β
β β McpServer (MCP Apps Pattern) β β
β β - registerAppTool(search_nasa...) β β
β β - registerAppTool(get_next_image) β β
β β - registerAppResource(viewer UI) β β
β β - registerResource(image URL) β β
β βββββββββββββββββββββββββββββββββββββββββ β
β βββββββββββββββββββββββββββββββββββββββββ β
β β Session Manager β β
β β - Manage search state per user β β
β βββββββββββββββββββββββββββββββββββββββββ β
β βββββββββββββββββββββββββββββββββββββββββ β
β β NASA API Client β β
β β - Image search β β
β β - Image URL retrieval β β
β βββββββββββββββββββββββββββββββββββββββββ β
βββββββββββββββββββββΌββββββββββββββββββββββββββ
β HTTPS
βββββββββββββββββββββΌββββββββββββββββββββββββββ
β NASA Images API β
β https://images-api.nasa.gov/search β
βββββββββββββββββββββββββββββββββββββββββββββββ
Main Components
- src/index.ts: Express server and transport management
- src/mcp-server.ts: MCP server logic (tool and resource registration)
- src/session-manager.ts: Session management (search state persistence)
- src/nasa-api.ts: NASA API client
- src/types.ts: TypeScript type definitions
Development
Watch Mode
Automatically rebuilds when files change.
Development Mode
Builds and immediately starts the server.
Troubleshooting
Port Already in Use
Error: listen EADDRINUSE: address already in use
Solution: Specify a different port: