# APRS.fi MCP Server

A Model Context Protocol (MCP) server that provides access to APRS.fi API for ham radio position tracking and balloon chase operations. Designed specifically for integration with Claude Code to enable AI-powered APRS data analysis and ham radio operations.

## Features

- **get_aprs_position**: Get current position data for a specific callsign
- **get_aprs_history**: Get position history for a callsign with time range
- **track_multiple_callsigns**: Track multiple callsigns at once
- **validate_aprs_key**: Test if an APRS.fi API key is valid
- **Claude Code Integration**: Natural language interface for APRS data analysis

## Quick Installation for Claude Code

**Easiest Setup (Claude MCP):**

```bash
npm run build
claude mcp add aprs-fi node dist/index.js
```

**Alternative (Install Script):**

```bash
./install.sh
```

For detailed setup instructions, see [SETUP.md](SETUP.md).

## Manual Installation

1. Install dependencies:
```bash
npm install
```

2. Build the server:
```bash
npm run build
```

## Usage

### Starting the Server

```bash
npm start
```

### Development Mode

```bash
npm run dev
```

### From Main Project

```bash
# Build MCP server
npm run mcp:build

# Start MCP server
npm run mcp:start

# Development mode
npm run mcp:dev
```

## MCP Tools

### get_aprs_position

Get current position data for a specific callsign from APRS.fi.

**Parameters:**
- `callsign` (string, required): The callsign to look up (e.g., "W1AW")
- `apiKey` (string, optional): APRS.fi API key (can be set via `/set-api-key` command)

**Returns:** Array of APRSPosition objects

### get_aprs_history

Get position history for a callsign with time range.

**Parameters:**
- `callsign` (string, required): The callsign to look up
- `apiKey` (string, optional): APRS.fi API key (can be set via `/set-api-key` command)
- `lastHours` (number, optional): Number of hours to look back (default: 24)

**Returns:** Array of APRSPosition objects sorted by timestamp

### track_multiple_callsigns

Track multiple callsigns at once.

**Parameters:**
- `callsigns` (array, required): Array of callsigns to track
- `apiKey` (string, optional): APRS.fi API key (can be set via `/set-api-key` command)

**Returns:** Array of APRSPosition objects

### validate_aprs_key

Test if an APRS.fi API key is valid.

**Parameters:**
- `apiKey` (string, optional): APRS.fi API key (can be set via `/set-api-key` command) to validate

**Returns:** Object with `valid` boolean property

## Data Types

### APRSPosition

```typescript
interface APRSPosition {
  name: string;           // Callsign
  callsign: string;       // Callsign
  lat: number;           // Latitude in decimal degrees
  lng: number;           // Longitude in decimal degrees
  altitude?: number;     // Altitude in meters (optional)
  timestamp: number;     // Unix timestamp in milliseconds
  comment?: string;      // APRS comment (optional)
  speed?: number;        // Speed in km/h (optional)
  course?: number;       // Course in degrees (optional)
  symbol?: string;       // APRS symbol (optional)
  path?: string;         // APRS path (optional)
}
```

## API Key Setup

1. Get an API key from [APRS.fi](https://aprs.fi/page/api)
2. Set it once per session using the `/set-api-key` command in Claude Code
3. Alternatively, pass the API key as a parameter to each tool call

## Rate Limiting

The server respects APRS.fi rate limits with a 1-second delay between requests.

## Error Handling

The server provides detailed error messages for:
- Invalid API keys
- Network connectivity issues
- API rate limiting
- Invalid callsigns
- API response errors

## Claude Code Integration

This MCP server enables Claude Code to access real-time APRS data, making it perfect for:
- **Ham Radio Operations**: Track stations, analyze propagation, coordinate activities
- **Emergency Communications**: Monitor emergency nets and station positions
- **Balloon Chasing**: Track high-altitude balloons and coordinate recovery teams
- **Contest Support**: Monitor contest stations and optimize operations
- **Educational Projects**: Learn about RF propagation and amateur radio

### Setup for Claude Code

**Easiest Setup (Claude MCP):**
```bash
# Build the server first
npm run build

# Add to Claude Code
claude mcp add aprs-fi node dist/index.js
```

**Alternative Setup (Install Script):**
```bash
./install.sh
```

**Manual Configuration:**
Add this to your `~/.claude/mcp_settings.json`:

```json
{
  "mcpServers": {
    "aprs-fi": {
      "command": "node",
      "args": ["/path/to/aprs_mcp/dist/index.js"],
      "env": {}
    }
  }
}
```

### Using with Claude Code

Once installed, Claude Code can help you with APRS data in natural language:

- "Show me the current position of W1AW"
- "Track these contest stations: N1MM, W5ZZZ, K3LR"  
- "Get the position history for the balloon callsign KC1SFR-11"
- "Find all stations that have been active in the last 2 hours"
- "Plot the path of station VE3XYZ over the last 6 hours"

Claude Code will use the MCP tools to fetch real-time data and provide analysis, mapping suggestions, and operational insights.

## Slash Commands

- `/set-api-key <your-key>` - Set APRS.fi API key for the session

## Development

The server is built using:
- [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/typescript-sdk)
- TypeScript
- Node.js fetch API

## License

MIT