N2YO Satellite Tracker MCP Server

# N2YO Satellite Tracker MCP Server A Model Context Protocol (MCP) server that provides access to N2YO satellite tracking data, including TLE (Two-Line Element) data, satellite positions, and pass predictions. ## Overview This MCP server integrates with the N2YO.com API to provide satellite tracking capabilities. N2YO is a real-time satellite tracking service that offers comprehensive data on satellites, including military, weather, GPS, amateur radio, and commercial satellites. ### Key Features - **Natural Language Queries**: Ask questions like "What satellites will be over France at 6:00 tonight?" - **TLE Data Access**: Get Two-Line Element data for any satellite by NORAD ID - **Category-based Search**: Find satellites by type (military, weather, GPS, etc.) - **Country Filtering**: Filter satellites by country or organization - **Real-time Positioning**: Get current satellite positions relative to observer - **Pass Predictions**: Predict when satellites will be visible from your location - **Overhead Tracking**: Find all satellites currently above a specific location - **⭐ Radio Pass Optimization**: Communication windows for amateur radio operators - **⭐ Satellite Name Search**: Find satellites by name instead of NORAD ID - **⭐ Recent Launch Tracking**: Monitor newly deployed satellites - **⭐ Space Debris Monitoring**: Track debris for collision avoidance - **⭐ Trajectory Visualization**: Get satellite paths over time ## Installation ```bash git clone <repository-url> cd n2yo-satellite-tracker-mcp npm install npm run build ``` ## Setup 1. **Get N2YO API Key**: Register at [N2YO.com](https://www.n2yo.com/) and generate an API key from your profile 2. **Configure the server**: - **Option A** (Recommended): Set environment variable `N2YO_API_KEY=your-api-key` - **Option B**: Use the `set_n2yo_api_key` tool to configure your API key during runtime 3. **Start tracking**: Use the various tools to track satellites ## Usage ```bash # Option A: Set API key via environment variable (recommended) N2YO_API_KEY=your-api-key npm start # Option B: Start server and set API key via tool later npm start ``` The server connects to MCP-compatible clients via stdio transport. ## Tools Available ### `set_n2yo_api_key` Configure your N2YO API key for accessing satellite data. **Parameters:** - `apiKey` (required): Your N2YO API key ### `query_satellites_natural` Answer natural language questions about satellites (🌟 **NEW FEATURE**). **Parameters:** - `query` (required): Natural language query like "What satellites will be over France at 6:00 tonight?" - `categoryFilter` (optional): Filter by category: "all", "military", "weather", "gps", "amateur", "starlink", "space-stations" **Supported Query Patterns:** - **Location**: Countries (France, Germany, USA), cities (Paris, London, New York) - **Time**: "tonight", "6:00 PM", "tomorrow morning", "in 2 hours", "now" - **Categories**: Can be specified in query or categoryFilter parameter ### `query_satellites_with_tle` Find satellites by natural language query and return structured data with Name and TLE (🌟 **NEW FEATURE**). **Parameters:** - `query` (required): Natural language query about satellites (e.g., 'ISS', 'Starlink satellites over California', 'military satellites') - `categoryFilter` (optional): Filter by category: "all", "military", "weather", "gps", "amateur", "starlink", "space-stations" - `maxResults` (optional): Maximum number of satellites to return (default: 10) **Returns structured JSON with:** - Satellite names and NORAD IDs - Complete TLE data for each satellite - Position information - Query metadata ### `get_satellite_tle` Get Two-Line Element (TLE) data for a specific satellite. **Parameters:** - `noradId` (required): NORAD catalog number (e.g., "25544" for ISS) ### `get_satellites_by_category` Browse satellites by predefined categories. **Parameters:** - `category` (required): One of: "military", "weather", "gps", "navigation", "amateur", "geostationary", "noaa", "starlink", "space-stations", "earth-resources" - `country` (optional): Country code filter (e.g., "usa", "china", "russia") ### `get_satellite_position` Get current position of a satellite relative to an observer location. **Parameters:** - `noradId` (required): NORAD catalog number - `observerLat` (required): Observer latitude (-90 to 90) - `observerLng` (required): Observer longitude (-180 to 180) - `observerAlt` (optional): Observer altitude in meters (default: 0) - `seconds` (optional): Seconds in future for prediction (0-300, default: 0) ### `get_visual_passes` Get upcoming visual passes of a satellite for an observer location. **Parameters:** - `noradId` (required): NORAD catalog number - `observerLat` (required): Observer latitude (-90 to 90) - `observerLng` (required): Observer longitude (-180 to 180) - `observerAlt` (optional): Observer altitude in meters (default: 0) - `days` (optional): Days to look ahead (1-10, default: 10) - `minVisibility` (optional): Minimum visibility in seconds (1-300, default: 300) ### `get_satellites_above` Get all satellites currently above an observer location. **Parameters:** - `observerLat` (required): Observer latitude (-90 to 90) - `observerLng` (required): Observer longitude (-180 to 180) - `observerAlt` (optional): Observer altitude in meters (default: 0) - `searchRadius` (optional): Search radius in degrees (1-90, default: 70) - `categoryFilter` (optional): Filter by category or "all" (default: "all") ### `get_radio_passes` ⭐ **NEW** Get upcoming radio communication passes optimized for amateur radio operators. **Parameters:** - `noradId` (required): NORAD catalog number - `observerLat` (required): Observer latitude (-90 to 90) - `observerLng` (required): Observer longitude (-180 to 180) - `observerAlt` (optional): Observer altitude in meters (default: 0) - `days` (optional): Days to look ahead (1-10, default: 10) - `minElevation` (optional): Minimum elevation in degrees (1-90, default: 10) ### `search_satellites_by_name` ⭐ **NEW** Search for satellites by name or international designator. **Parameters:** - `query` (required): Search term (satellite name or international designator) **Example queries:** "ISS", "Starlink", "NOAA", "GPS", "1998-067A" ### `get_recent_launches` ⭐ **NEW** Get satellites launched in the last 30 days. **Parameters:** None ### `get_space_debris` ⭐ **NEW** Track space debris above an observer location for collision avoidance. **Parameters:** - `observerLat` (required): Observer latitude (-90 to 90) - `observerLng` (required): Observer longitude (-180 to 180) - `observerAlt` (optional): Observer altitude in meters (default: 0) - `searchRadius` (optional): Search radius in degrees (1-90, default: 70) ### `get_satellite_trajectory` ⭐ **NEW** Get satellite trajectory over time for visualization and planning. **Parameters:** - `noradId` (required): NORAD catalog number - `observerLat` (required): Observer latitude (-90 to 90) - `observerLng` (required): Observer longitude (-180 to 180) - `observerAlt` (optional): Observer altitude in meters (default: 0) - `seconds` (optional): Time period in seconds (1-3600, default: 300) ## Resources Available ### `n2yo://api/status` Current N2YO API configuration and usage status including: - API key configuration status - Transaction counts for each endpoint - Daily API limits ### `n2yo://categories/list` Available satellite categories for searching: - Military satellites - Weather satellites - GPS operational satellites - Amateur radio satellites - And more... ### `n2yo://countries/list` Available countries and organizations for satellite filtering. ### `n2yo://limits/info` Information about N2YO API transaction limits and current usage. ## Natural Language Query Capabilities The `query_satellites_natural` tool can understand and parse various natural language patterns: ### **Supported Locations** (100+ countries and cities) - **Countries**: France, Germany, USA, China, Russia, Japan, UK, Canada, Australia, etc. - **Major Cities**: Paris, London, New York, Tokyo, Berlin, Moscow, Sydney, etc. - **Query Examples**: - "over France" - "above Germany" - "in New York" ### **Supported Time Expressions** - **Relative Times**: "tonight", "tomorrow", "now", "right now" - **Specific Times**: "6:00 PM", "18:00", "6:00 tonight" - **Future Times**: "in 2 hours", "tomorrow morning" - **Query Examples**: - "at 6:00 tonight" - "tomorrow morning" - "in 3 hours" ### **Example Natural Language Queries** - "What satellites will be over France at 6:00 tonight?" - "Show me military satellites above Germany now" - "What Starlink satellites are over New York right now?" - "Which satellites will be above Tokyo tomorrow morning?" - "Find weather satellites over London in 2 hours" ## Satellite Categories The server supports the following satellite categories: - **military** (30): Military satellites - **weather** (3): Weather satellites - **gps** (20): GPS operational satellites - **navigation** (24): Navy Navigation Satellite System - **amateur** (18): Amateur radio satellites - **geostationary** (10): Geostationary satellites - **noaa** (4): NOAA satellites - **starlink** (52): Starlink constellation - **space-stations** (2): International Space Station and others - **earth-resources** (6): Earth observation satellites ## Example Usage ### Configure API Key ```json { "tool": "set_n2yo_api_key", "arguments": { "apiKey": "YOUR-N2YO-API-KEY" } } ``` ### Natural Language Queries (🌟 **NEW**) ```json { "tool": "query_satellites_natural", "arguments": { "query": "What satellites will be over France at 6:00 tonight?" } } ``` ```json { "tool": "query_satellites_natural", "arguments": { "query": "Show me military satellites above Germany now", "categoryFilter": "military" } } ``` ```json { "tool": "query_satellites_natural", "arguments": { "query": "What Starlink satellites are over New York right now?", "categoryFilter": "starlink" } } ``` ### Get ISS TLE Data ```json { "tool": "get_satellite_tle", "arguments": { "noradId": "25544" } } ``` ### Find Military Satellites ```json { "tool": "get_satellites_by_category", "arguments": { "category": "military", "country": "usa" } } ``` ### Track ISS Position ```json { "tool": "get_satellite_position", "arguments": { "noradId": "25544", "observerLat": 40.7128, "observerLng": -74.0060, "observerAlt": 0 } } ``` ### Get ISS Pass Predictions ```json { "tool": "get_visual_passes", "arguments": { "noradId": "25544", "observerLat": 40.7128, "observerLng": -74.0060, "days": 7 } } ``` ### Find Satellites Overhead ```json { "tool": "get_satellites_above", "arguments": { "observerLat": 40.7128, "observerLng": -74.0060, "searchRadius": 80, "categoryFilter": "military" } } ``` ### Radio Communication Passes ⭐ **NEW** ```json { "tool": "get_radio_passes", "arguments": { "noradId": "25544", "observerLat": 40.7128, "observerLng": -74.0060, "days": 7, "minElevation": 15 } } ``` ### Search Satellites by Name ⭐ **NEW** ```json { "tool": "search_satellites_by_name", "arguments": { "query": "ISS" } } ``` ### Recent Launches ⭐ **NEW** ```json { "tool": "get_recent_launches", "arguments": {} } ``` ### Space Debris Tracking ⭐ **NEW** ```json { "tool": "get_space_debris", "arguments": { "observerLat": 40.7128, "observerLng": -74.0060, "searchRadius": 85 } } ``` ### Satellite Trajectory ⭐ **NEW** ```json { "tool": "get_satellite_trajectory", "arguments": { "noradId": "25544", "observerLat": 40.7128, "observerLng": -74.0060, "seconds": 600 } } ``` ## API Limits N2YO provides free API access with the following daily limits: - **TLE requests**: 1,000 per day - **Position requests**: 1,000 per day - **Visual passes**: 100 per day - **Radio passes**: 100 per day ⭐ - **Above requests**: 100 per day - **Launch date requests**: 100 per day ⭐ ## Development ```bash # Watch mode for development npm run dev # Build for production npm run build # Start the server npm start ``` ## Popular Satellites Some commonly tracked satellites you can use for testing: - **ISS**: 25544 - **Hubble Space Telescope**: 20580 - **GPS satellites**: Use category "gps" - **Starlink**: Use category "starlink" - **Weather satellites**: Use category "weather" ## Contributing 1. Fork the repository 2. Create a feature branch 3. Make your changes 4. Add tests if applicable 5. Submit a pull request ## License MIT License - see LICENSE file for details. ## Related Links - [N2YO.com](https://www.n2yo.com/) - Real-time satellite tracking - [N2YO API Documentation](https://www.n2yo.com/api/) - [Model Context Protocol](https://modelcontextprotocol.io/) - Learn about MCP - [NORAD Catalog](https://celestrak.com/) - Satellite catalog information