N2YO MCP

🚀 N2YO Satellite Tracker MCP Server

This is a Model Context Protocol (MCP) server that offers access to N2YO satellite tracking data. It provides TLE (Two-Line Element) data, satellite positions, and pass predictions, enabling users to track satellites effectively.

🚀 Quick Start

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 various satellites, including military, weather, GPS, amateur radio, and commercial ones.

✨ Features

• Natural Language Queries: Pose questions such as "What satellites will be over France at 6:00 tonight?"
• TLE Data Access: Retrieve Two - Line Element data for any satellite using its NORAD ID.
• Category - based Search: Find satellites according to their type (military, weather, GPS, etc.).
• Country Filtering: Filter satellites by country or organization.
• Real - time Positioning: Obtain the current positions of satellites relative to the observer.
• Pass Predictions: Predict when satellites will be visible from your location.
• Overhead Tracking: Locate all satellites currently above a specific location.
• ⭐ Radio Pass Optimization: Provide communication windows for amateur radio operators.
• ⭐ Satellite Name Search: Find satellites by their names instead of NORAD IDs.
• ⭐ Recent Launch Tracking: Monitor newly deployed satellites.
• ⭐ Space Debris Monitoring: Track debris to avoid collisions.
• ⭐ Trajectory Visualization: Get satellite paths over time.

📦 Installation

git clone <repository - url>
cd n2yo - satellite - tracker - mcp
npm install
npm run build

📚 Documentation

Setup

1. Get N2YO API Key: Register at N2YO.com and generate an API key from your profile.
2. Configure the server:
   • Option A (Recommended): Set the 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: Utilize 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): A 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, etc.), cities (Paris, London, New York, etc.)
• Time: "tonight", "6:00 PM", "tomorrow morning", "in 2 hours", "now"
• Categories: Can be specified in the query or the 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): A 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): The 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 the 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 the 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, and daily API limits.
• n2yo://categories/list: Available satellite categories for searching, such as military satellites, weather satellites, GPS operational satellites, amateur radio satellites, etc.
• 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:

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:

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

This project is under the MIT License. See the 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