Boston Harbor Ferries

APRS-based Boston Harbor commuter ferry tracker with MCP server support.

Tightly scoped to track Seaport Ferry vessels operating in Boston Harbor.

Data provided by aprs.fi - https://aprs.fi

Features

• Track all 4 Seaport Ferry vessels in real-time
• In-memory caching with 120-second TTL (respects aprs.fi API terms)
• Rate limiting: 10 requests/minute (configurable)
• Rich CLI with beautiful terminal output
• MCP server for integration with Claude Code and other AI assistants
• Run with uvx (no installation required)
• Live position tracking and historical data export

Tracked Vessels

Seaport Ferry - North Station Route

• PHILLIS WHEATLEY (MMSI: 368227350)
• SAMUEL WHITTEMORE (MMSI: 368227370)
• COMMONWEALTH (MMSI: 368351390)

Route: LoveJoy Wharf (North Station) ↔ Fan Pier (Seaport) ↔ Pier 10 Travel time: ~30 minutes

Seaport Ferry - East Boston Route

• CRISPUS ATTUCKS (MMSI: 368157410) - 📍 Live Position

Route: Lewis Mall Wharf (East Boston) ↔ Fan Pier (Seaport) Travel time: ~10 minutes

🚢 Latest Position: 42.351318°N, 71.038918°W (Course: 339°) 📊 View 24-Day Activity Analysis - Speed patterns, hourly heatmaps, route visualization 📍 Live Position Data - Real-time JSON feed

Historical Data: 4,777 positions over 24 days (Sep 15 - Oct 10) • Avg speed: 12.4kn • Operating hours: 05:00-19:00

📊 Activity Heatmap (Last 2 Weeks)

Activity by hour - darker blocks indicate more position reports:

      00  04  08  12  16  20
      │   │   │   │   │   │
09-29 │    ░▓████▒ ░▒░███▓▒
09-30 │    ░▓████░  ▒▓████▒
10-01 │     ▒████▒    ████▒
10-02 │    ░▓████░    ████▒
10-03 │     ▓█████▓░▒▒████▒
10-06 │    ░▒████▓░▒▒▒████▒
10-07 │    ░▓████▒   ░████▒
10-08 │     ▓█░▓█░   ░████▒
10-09 │    ░█████▒▒█░▓████░
10-10 │    ░▓████▒

Legend: ░ Low ▒ Medium ▓ High █ Peak Pattern: Clear AM (06-10) and PM (15-18) commute peaks

🚢 Speed Distribution

Speed (knots) │ Frequency
──────────────┼──────────────────────────────────────────────────
        2- 4 │ ██████ 188
        4- 6 │ ███████ 202
        6- 8 │ █████ 148
        8-10 │ ██████ 176
       10-12 │ ████████ 229
       12-14 │ ████████████ 349
       14-16 │ ███████████████████████ 673
       16-18 │ ████████████████████████████████████████ 1123
       18-20 │ ███ 93
       20-22 │  21

Peak Speed: 16-18 knots (75% of time cruising >10kn)

🗺️ Route Map

           Boston Harbor
    ╔══════════════════════╗
    ║                      ║

  Lewis Mall Wharf    Fan Pier
   (East Boston)      (Seaport)
         │                │
         │   ~10 min      │
         │   8-12 kn      │
         └───────┬────────┘
                 │
            CRISPUS ATTUCKS
            (90 passengers)

Operating: 05:00-19:00 daily • Peak: 06-10, 15-18

---

Installation

Run with uvx (recommended)

# Set your API key
export APRS_API_KEY="your-key-from-aprs.fi"

# Run commands directly
uvx --from . harbor-ferry list-vessels
uvx --from . harbor-ferry track 368157410
uvx --from . harbor-ferry track-all

Install in development mode

cd boston_harbor_ferries
pip install -e .

Configuration

Get your free API key from https://aprs.fi (requires registration).

Set the API key via environment variable:

export APRS_API_KEY="your-api-key-here"

Or create a .env file:

APRS_API_KEY=your-api-key-here
APRS_CACHE_TTL_SECONDS=120
APRS_MAX_REQUESTS_PER_MINUTE=10

CLI Usage

# List all known ferries
harbor-ferry list-vessels

# Show routes and schedules
harbor-ferry routes

# Track a specific ferry
harbor-ferry track 368157410

# Track all ferries
harbor-ferry track-all

# Force fresh data (bypass cache)
harbor-ferry track 368157410 --no-cache

# Cache management
harbor-ferry cache-info
harbor-ferry clear-cache

MCP Server Usage

The MCP server allows AI assistants like Claude Code to track ferries in real-time.

Quick Start

# Test the MCP server
gmake test-mcp

# Expected output:
# ✓ MCP server responding to JSON-RPC
# Tools: list_ferries, track_ferry, track_all_ferries, get_ferry_routes, clear_cache

Available MCP Tools

• list_ferries - List all known Boston Harbor ferries with details
• get_ferry_routes - Get route information and schedules
• track_ferry - Track specific ferry by MMSI number
• track_all_ferries - Get all ferry positions at once
• clear_cache - Force fresh data (bypasses 2-minute cache)

Claude Code/Desktop Integration

See docs/CLAUDE_CODE_INTEGRATION.md for complete integration guide.

Adding to Claude Code

From within this repository directory:

# Add the MCP server to Claude Code
claude mcp add-json boston-harbor-ferries \
  '{"command":"uv","args":["run","python","-m","boston_harbor_ferries.mcp_server"],"env":{"APRS_API_KEY":"'"${APRS_API_KEY}"'"}}'

# Verify it's connected
claude mcp list
# Should show: boston-harbor-ferries - ✓ Connected

# View available tools
claude mcp get boston-harbor-ferries

Claude Desktop Configuration

For global access in all Claude Desktop conversations:

Linux: ~/.config/Claude/claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "boston-harbor-ferries": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/full/path/to/boston-harbor-ferries",
        "python",
        "-m",
        "boston_harbor_ferries.mcp_server"
      ],
      "env": {
        "APRS_API_KEY": "your-api-key-here"
      }
    }
  }
}

Example Questions for Claude

Once configured, you can ask Claude:

• "Where is CRISPUS ATTUCKS right now?"
• "Show me all active ferries"
• "What are the ferry routes in Boston Harbor?"
• "Clear the cache and check ferry positions again"

Understanding Position Data

Operating Hours: Ferries transmit APRS positions during service hours (05:00-19:00 daily)

• Peak times: 06:00-10:00 (morning) and 15:00-18:00 (evening)
• Off-hours: No position data when ferries are not operating
• Data age: Position reports update every 1-2 minutes when active

If you see old position data (>1 hour), the ferry is likely docked between runs or service has ended for the day. Check during peak commute hours for live tracking.

All 6 MCP tools tested and working ✅ (see gmake test)

Bonus: FreeBSD Leave Reminder MCP Server

This repository also includes a standalone MCP server that wraps FreeBSD's leave(1) command for setting reminders.

See LEAVE_MCP.md for complete documentation.

Quick test:

gmake test-leave-mcp

Tools available:

• set_reminder - Set a reminder for a specific time or duration
• check_reminders - View active reminders
• cancel_reminders - Cancel all reminders

Example: "Remind me to leave in 30 minutes" → Uses +0030 format

Python API

from boston_harbor_ferries import APRSClient, VESSELS

# Initialize client (loads API key from env)
with APRSClient() as client:
    # Track specific ferry
    position = client.get_vessel_position("368157410")
    if position:
        print(f"{position.vessel.name} at {position.latitude}, {position.longitude}")

    # Track all ferries
    positions = client.get_all_ferries()
    for pos in positions:
        print(f"{pos.vessel.name}: {pos.age_seconds:.0f}s old")

API Terms Compliance

This tool complies with aprs.fi API terms of service:

• ✅ Credits aprs.fi as data source in all output
• ✅ Provides link back to aprs.fi
• ✅ Free to use for all users
• ✅ Includes User-Agent header with app name/version
• ✅ Each user uses their own API key
• ✅ Built-in rate limiting (10 req/min default)
• ✅ Intelligent caching (2 min TTL default)
• ✅ Only queries when actively needed (no background polling)

Development

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Type checking
mypy boston_harbor_ferries

License

MIT

Acknowledgments

Data provided by aprs.fi - Hessu's excellent APRS infrastructure service.

Ferry service operated by Seaport Ferry.