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
git clone <repository-url>
cd n2yo-satellite-tracker-mcp
npm install
npm run build
Setup
- Get N2YO API Key: Register at N2YO.com and generate an API key from your profile
- Configure the server:
- Option A (Recommended): Set environment variable
N2YO_API_KEY=your-api-key - Option B: Use the
set_n2yo_api_keytool to configure your API key during runtime
- Option A (Recommended): Set environment variable
- Start tracking: Use the various tools to track satellites
Usage
# 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 numberobserverLat(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 numberobserverLat(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 numberobserverLat(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 numberobserverLat(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
{
"tool": "set_n2yo_api_key",
"arguments": {
"apiKey": "YOUR-N2YO-API-KEY"
}
}
Natural Language Queries (🌟 NEW)
{
"tool": "query_satellites_natural",
"arguments": {
"query": "What satellites will be over France at 6:00 tonight?"
}
}
{
"tool": "query_satellites_natural",
"arguments": {
"query": "Show me military satellites above Germany now",
"categoryFilter": "military"
}
}
{
"tool": "query_satellites_natural",
"arguments": {
"query": "What Starlink satellites are over New York right now?",
"categoryFilter": "starlink"
}
}
Get ISS TLE Data
{
"tool": "get_satellite_tle",
"arguments": {
"noradId": "25544"
}
}
Find Military Satellites
{
"tool": "get_satellites_by_category",
"arguments": {
"category": "military",
"country": "usa"
}
}
Track ISS Position
{
"tool": "get_satellite_position",
"arguments": {
"noradId": "25544",
"observerLat": 40.7128,
"observerLng": -74.0060,
"observerAlt": 0
}
}
Get ISS Pass Predictions
{
"tool": "get_visual_passes",
"arguments": {
"noradId": "25544",
"observerLat": 40.7128,
"observerLng": -74.0060,
"days": 7
}
}
Find Satellites Overhead
{
"tool": "get_satellites_above",
"arguments": {
"observerLat": 40.7128,
"observerLng": -74.0060,
"searchRadius": 80,
"categoryFilter": "military"
}
}
Radio Communication Passes ⭐ NEW
{
"tool": "get_radio_passes",
"arguments": {
"noradId": "25544",
"observerLat": 40.7128,
"observerLng": -74.0060,
"days": 7,
"minElevation": 15
}
}
Search Satellites by Name ⭐ NEW
{
"tool": "search_satellites_by_name",
"arguments": {
"query": "ISS"
}
}
Recent Launches ⭐ NEW
{
"tool": "get_recent_launches",
"arguments": {}
}
Space Debris Tracking ⭐ NEW
{
"tool": "get_space_debris",
"arguments": {
"observerLat": 40.7128,
"observerLng": -74.0060,
"searchRadius": 85
}
}
Satellite Trajectory ⭐ NEW
{
"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
# 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
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if applicable
- Submit a pull request
License
MIT License - see LICENSE file for details.
Related Links
- N2YO.com - Real-time satellite tracking
- N2YO API Documentation
- Model Context Protocol - Learn about MCP
- NORAD Catalog - Satellite catalog information