{
  "markdown": "# NASA Images MCP Server\n\nA project to search NASA's image library using an MCP server and display images in an interactive UI.\n\n**🌟 Features:**\n- **Dual Transport Support**: Supports both stdio and Streamable HTTP transport\n- **Image Search**: Search by keywords using NASA's Images API\n- **Interactive UI**: Beautiful image viewer using MCP Apps Pattern\n- **Image Navigation**: Display search results sequentially\n- **Session Management**: Stateful session management\n\n![screenshot](nasa-images-mcp.gif)\n\n## Requirements\n\n- Node.js 18 or higher\n- npm or yarn\n- NASA API Key (get free at [nasa.gov/api](https://api.nasa.gov/))\n\n## Installation\n\n1. Clone the repository:\n```bash\ncd nasa-images-mcp-server\n```\n\n2. Install dependencies:\n```bash\nnpm install\n```\n\n3. Set up environment variables:\n```bash\ncp .env.example .env\n```\n\nEdit the `.env` file to configure your NASA API key:\n```env\nNASA_API_KEY=your_api_key_here\nPORT=3000\n```\n\n4. Build:\n```bash\nnpm run build\n```\n\n## Getting a NASA API Key\n\n1. Visit [https://api.nasa.gov/](https://api.nasa.gov/)\n2. Enter your name and email address in the form\n3. The API key will be sent to your email immediately\n4. Add it to your `.env` file\n\n**Rate Limits:**\n- DEMO_KEY: 30 requests/hour, 50 requests/day\n- Registered key: 1000 requests/hour\n\n## Usage\n\n### stdio Mode (Recommended for MCP Clients like Claude Desktop)\n\nIn stdio mode, the server communicates via stdin/stdout — no HTTP server is started. Logs are written to stderr.\n\n#### Run with npx (no installation required)\n\n```bash\nnpx @kaitoy/nasa-images-mcp-server --stdio\n```\n\n#### Run from local build\n\nPass the `--stdio` flag to use stdio transport:\n\n```bash\nnode build/index.js --stdio\n```\n\n#### Claude Desktop Configuration\n\n**Using npx** (recommended):\n\n```json\n{\n  \"mcpServers\": {\n    \"nasa-images\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@kaitoy/nasa-images-mcp-server\", \"--stdio\"],\n      \"env\": {\n        \"NASA_API_KEY\": \"your_api_key_here\"\n      }\n    }\n  }\n}\n```\n\n**Using local build**:\n\n```json\n{\n  \"mcpServers\": {\n    \"nasa-images\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/nasa-images-mcp-server/build/index.js\", \"--stdio\"],\n      \"env\": {\n        \"NASA_API_KEY\": \"your_api_key_here\"\n      }\n    }\n  }\n}\n```\n\n### HTTP Server Mode\n\n```bash\nnpm start\n```\n\nThe server will start at `http://localhost:3000`.\n\n### Start on a Different Port\n\n```bash\nPORT=3001 npm start\n```\n\n## About Transports\n\n### stdio Transport\n\nSuitable for local MCP clients (e.g., Claude Desktop) that launch the server as a subprocess.\n\n- Communicates via stdin/stdout\n- Single session per process\n- No network configuration required\n\n### Streamable HTTP Transport\n\nThe latest MCP HTTP transport protocol, suitable for remote or multi-client scenarios.\n\n**Key Features:**\n- ✅ **Stateful Sessions**: Issues a unique session ID for each client\n- ✅ **SSE Support**: Supports push notifications from the server via Server-Sent Events\n- ✅ **JSON-RPC over HTTP**: Communication via standard HTTP request/response\n- ✅ **Session Management**: Automatic session lifecycle management\n\n## Integration with MCP Clients\n\n### Connecting with MCP Inspector (HTTP mode)\n\nYou can test the server using [MCP Inspector](https://github.com/modelcontextprotocol/inspector):\n\n```bash\nnpx @modelcontextprotocol/inspector http://localhost:3000/mcp\n```\n\n### Connecting with MCP Inspector (stdio mode)\n\n```bash\nnpx @modelcontextprotocol/inspector node /path/to/nasa-images-mcp-server/build/index.js --stdio\n```\n\n### Using with Custom MCP Clients\n\nSteps to connect from a custom client:\n\n1. **Initialize Request** (POST /mcp):\n```bash\ncurl -X POST http://localhost:3000/mcp \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Accept: application/json, text/event-stream\" \\\n  -d '{\n    \"jsonrpc\": \"2.0\",\n    \"id\": 1,\n    \"method\": \"initialize\",\n    \"params\": {\n      \"protocolVersion\": \"2024-11-05\",\n      \"capabilities\": {},\n      \"clientInfo\": {\n        \"name\": \"my-client\",\n        \"version\": \"1.0.0\"\n      }\n    }\n  }'\n```\n\nThe response headers will include `mcp-session-id`.\n\n2. **Subsequent Requests**:\n```bash\ncurl -X POST http://localhost:3000/mcp \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Accept: application/json, text/event-stream\" \\\n  -H \"mcp-session-id: <your-session-id>\" \\\n  -d '{\n    \"jsonrpc\": \"2.0\",\n    \"id\": 2,\n    \"method\": \"tools/list\"\n  }'\n```\n\n3. **SSE Stream** (GET /mcp):\n```bash\ncurl -X GET \"http://localhost:3000/mcp\" \\\n  -H \"mcp-session-id: <your-session-id>\" \\\n  -H \"Accept: text/event-stream\"\n```\n\n## Endpoints\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/` | GET | Server information and endpoint list |\n| `/health` | GET | Health check (includes active session count) |\n| `/mcp` | POST | JSON-RPC requests (initialization, tool calls, etc.) |\n| `/mcp` | GET | SSE stream (for server notifications) |\n| `/mcp` | DELETE | Close session |\n\n## Available Tools\n\n### 1. `search_nasa_images`\n\nSearch NASA's image library.\n\n**Parameters:**\n- `query` (string, required): Search query (e.g., \"apollo 11\", \"mars rover\")\n\n**Usage Example (JSON-RPC):**\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 3,\n  \"method\": \"tools/call\",\n  \"params\": {\n    \"name\": \"search_nasa_images\",\n    \"arguments\": {\n      \"query\": \"apollo 11 moon landing\"\n    }\n  }\n}\n```\n\n### 2. `get_next_image`\n\nDisplay the next image from the current search results.\n\n**Parameters:**\nNone\n\n**Usage Example (JSON-RPC):**\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 4,\n  \"method\": \"tools/call\",\n  \"params\": {\n    \"name\": \"get_next_image\",\n    \"arguments\": {}\n  }\n}\n```\n\n## Available Resources\n\n### `nasa-image://current`\n\nGet the URL of the currently displayed image.\n\n**MIME Type:** `text/uri-list`\n\n### `ui://nasa-images/viewer`\n\nHTML UI resource for the image viewer.\n\n**MIME Type:** `text/html;profile=mcp-app`\n\n## Architecture\n\n### stdio Mode\n\n```\n┌─────────────────────────────────────────────┐\n│     MCP Client (Claude Desktop, etc.)       │\n│                   ↕ stdin/stdout            │\n└───────────────────┼─────────────────────────┘\n                    │\n┌───────────────────┼─────────────────────────┐\n│  NASA Images MCP Server                     │\n│  ┌────────────────┴──────────────────────┐  │\n│  │  StdioServerTransport                 │  │\n│  └───────────────────────────────────────┘  │\n│  ┌───────────────────────────────────────┐  │\n│  │  McpServer (MCP Apps Pattern)         │  │\n│  │  - registerAppTool(search_nasa...)    │  │\n│  │  - registerAppTool(get_next_image)    │  │\n│  │  - registerAppResource(viewer UI)     │  │\n│  │  - registerResource(image URL)        │  │\n│  └───────────────────────────────────────┘  │\n│  ┌───────────────────────────────────────┐  │\n│  │  Session Manager                      │  │\n│  │  - Manage search state per user       │  │\n│  └───────────────────────────────────────┘  │\n│  ┌───────────────────────────────────────┐  │\n│  │  NASA API Client                      │  │\n│  │  - Image search                       │  │\n│  │  - Image URL retrieval                │  │\n│  └───────────────────────────────────────┘  │\n└───────────────────┼─────────────────────────┘\n                    │ HTTPS\n┌───────────────────┼─────────────────────────┐\n│         NASA Images API                     │\n│  https://images-api.nasa.gov/search         │\n└─────────────────────────────────────────────┘\n```\n\n### HTTP Mode\n\n```\n┌─────────────────────────────────────────────┐\n│     MCP Client (Inspector, Custom App)      │\n│                                             │\n│  ┌────────────────────────────────────────┐ │\n│  │  HTTP Client                           │ │\n│  │  - POST /mcp (JSON-RPC requests)       │ │\n│  │  - GET /mcp (SSE stream)               │ │\n│  └────────────────────────────────────────┘ │\n│                   ↕                         │\n└───────────────────┼─────────────────────────┘\n                    │ HTTP/SSE\n┌───────────────────┼─────────────────────────┐\n│  NASA Images MCP Server (Express)           │\n│  ┌────────────────┴──────────────────────┐  │\n│  │  StreamableHTTPServerTransport        │  │\n│  │  - Session management                 │  │\n│  │  - JSON-RPC over HTTP                 │  │\n│  │  - SSE for notifications              │  │\n│  └───────────────────────────────────────┘  │\n│  ┌───────────────────────────────────────┐  │\n│  │  McpServer (MCP Apps Pattern)         │  │\n│  │  - registerAppTool(search_nasa...)    │  │\n│  │  - registerAppTool(get_next_image)    │  │\n│  │  - registerAppResource(viewer UI)     │  │\n│  │  - registerResource(image URL)        │  │\n│  └───────────────────────────────────────┘  │\n│  ┌───────────────────────────────────────┐  │\n│  │  Session Manager                      │  │\n│  │  - Manage search state per user       │  │\n│  └───────────────────────────────────────┘  │\n│  ┌───────────────────────────────────────┐  │\n│  │  NASA API Client                      │  │\n│  │  - Image search                       │  │\n│  │  - Image URL retrieval                │  │\n│  └───────────────────────────────────────┘  │\n└───────────────────┼─────────────────────────┘\n                    │ HTTPS\n┌───────────────────┼─────────────────────────┐\n│         NASA Images API                     │\n│  https://images-api.nasa.gov/search         │\n└─────────────────────────────────────────────┘\n```\n\n### Main Components\n\n- **src/index.ts**: Express server and transport management\n- **src/mcp-server.ts**: MCP server logic (tool and resource registration)\n- **src/session-manager.ts**: Session management (search state persistence)\n- **src/nasa-api.ts**: NASA API client\n- **src/types.ts**: TypeScript type definitions\n\n## Development\n\n### Watch Mode\n\n```bash\nnpm run watch\n```\n\nAutomatically rebuilds when files change.\n\n### Development Mode\n\n```bash\nnpm run dev\n```\n\nBuilds and immediately starts the server.\n\n## Troubleshooting\n\n### Port Already in Use\n\n```\nError: listen EADDRINUSE: address already in use\n```\n\n**Solution**: Specify a different port:\n```bash\nPORT=3001 npm start\n```\n\n### \"Cannot find module\" Error\n\nRun:\n```bash\nnpm run build\n```\n\nto compile TypeScript.\n\n### API Rate Limit Error\n\n- If using `DEMO_KEY`, obtain your own API key from [api.nasa.gov](https://api.nasa.gov/)\n- Limited to 30 requests per hour\n\n### \"Not Acceptable\" Error\n\nThe client must accept both MIME types:\n- `application/json`\n- `text/event-stream`\n\n```bash\ncurl -H \"Accept: application/json, text/event-stream\" ...\n```\n\n### Session Not Found\n\nSave the `mcp-session-id` header returned after the initialization request and send it as the `mcp-session-id` header in subsequent requests.\n\n## Security Notes\n\n- This server has CORS enabled (for development)\n- In production, implement proper CORS settings and rate limiting\n- Manage NASA API keys via environment variables; do not hardcode them\n\n## License\n\nMIT\n\n## References\n\n- [Model Context Protocol Specification](https://modelcontextprotocol.io/)\n- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)\n- [MCP Apps Extension](https://github.com/modelcontextprotocol/ext-apps)\n- [Streamable HTTP Transport](https://modelcontextprotocol.io/specification/draft/transport/http)\n- [NASA Images API](https://images.nasa.gov/docs/images.nasa.gov_api_docs.pdf)\n- [NASA Open APIs](https://api.nasa.gov/)\n\n## Contributing\n\nPull requests are welcome! Bug reports and feature requests are accepted via Issues.\n\n## Support\n\nIf you encounter issues, please create an Issue or refer to the NASA API support page.\n",
  "bytes": 11448,
  "sha": "bfa2c8528ca89b255234af521952577f3f3a2288494633126056f7445dd3ae7a",
  "repo_slug": "kaitoy/nasa-images-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_kaitoy_nasa_images_2718628e/readme"
}