Boston Harbor Ferries

![PyPI version](https://pypi.org/project/boston-harbor-ferries/) ![Python 3.10+](https://www.python.org/downloads/) ![License: MIT](https://opensource.org/licenses/MIT) ![Code style: ruff](https://github.com/astral-sh/ruff) ![APRS.fi](https://aprs.fi)

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: ``bash 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.

boston-harbor-ferries