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

screenshot

Requirements

Node.js 18 or higher
npm or yarn
NASA API Key (get free at nasa.gov/api)

Installation

Clone the repository:

bash

cd nasa-images-mcp-server

Install dependencies:

Terminal

npm install

Set up environment variables:

bash

cp .env.example .env

Edit the .env file to configure your NASA API key:

env

NASA_API_KEY=your_api_key_here
PORT=3000

Build:

Terminal

npm run 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)

Terminal

npx @kaitoy/nasa-images-mcp-server --stdio

Run from local build

Pass the --stdio flag to use stdio transport:

bash

node build/index.js --stdio

Claude Desktop Configuration

Using npx (recommended):

config.json

{
  "mcpServers": {
    "nasa-images": {
      "command": "npx",
      "args": ["-y", "@kaitoy/nasa-images-mcp-server", "--stdio"],
      "env": {
        "NASA_API_KEY": "your_api_key_here"
      }
    }
  }
}

Using local build:

config.json

{
  "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

Terminal

npm start

The server will start at http://localhost:3000.

Start on a Different Port

bash

PORT=3001 npm start

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:

Terminal

npx @modelcontextprotocol/inspector http://localhost:3000/mcp

Connecting with MCP Inspector (stdio mode)

Terminal

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):

Terminal

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:

Terminal

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):

Terminal

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):

config.json

{
  "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):

config.json

{
  "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

Code

┌─────────────────────────────────────────────┐
│     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

Code

┌─────────────────────────────────────────────┐
│     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

Terminal

npm run watch

Automatically rebuilds when files change.

Development Mode

Terminal

npm run dev

Builds and immediately starts the server.

Troubleshooting

Port Already in Use

Code

Error: listen EADDRINUSE: address already in use

Solution: Specify a different port:

bash

PORT=3001 npm start

"Cannot find module" Error

Run:

Terminal

npm run build

to compile TypeScript.

API Rate Limit Error

If using DEMO_KEY, obtain your own API key from api.nasa.gov
Limited to 30 requests per hour

"Not Acceptable" Error

The client must accept both MIME types:

application/json
text/event-stream

Terminal

curl -H "Accept: application/json, text/event-stream" ...

Session Not Found

Save the mcp-session-id header returned after the initialization request and send it as the mcp-session-id header in subsequent requests.

Security Notes

This server has CORS enabled (for development)
In production, implement proper CORS settings and rate limiting
Manage NASA API keys via environment variables; do not hardcode them

License

MIT

References

Contributing

Pull requests are welcome! Bug reports and feature requests are accepted via Issues.

Support

If you encounter issues, please create an Issue or refer to the NASA API support page.

NASA Images MCP Server

Requirements

Installation

Getting a NASA API Key

Usage

stdio Mode (Recommended for MCP Clients like Claude Desktop)

Run with npx (no installation required)

Run from local build

Claude Desktop Configuration

HTTP Server Mode

Start on a Different Port

About Transports

stdio Transport

Streamable HTTP Transport

Integration with MCP Clients

Connecting with MCP Inspector (HTTP mode)

Connecting with MCP Inspector (stdio mode)

Using with Custom MCP Clients

Endpoints

Available Tools

1. search_nasa_images

2. get_next_image

Available Resources

nasa-image://current

ui://nasa-images/viewer

Architecture

stdio Mode

HTTP Mode

Main Components

Development

Watch Mode

Development Mode

Troubleshooting

Port Already in Use

"Cannot find module" Error

API Rate Limit Error

"Not Acceptable" Error

Session Not Found

Security Notes

License

References

Contributing

Support

1. `search_nasa_images`

2. `get_next_image`

`nasa-image://current`

`ui://nasa-images/viewer`