boston-harbor-ferries 0.1.0

APRS-based Boston Harbor commuter ferry tracker with MCP server

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
• Built-in rate limiting and caching (respects aprs.fi API terms)
• Rich CLI with beautiful terminal output
• MCP server for integration with Claude Code and other AI assistants
• Run with uvx (no installation required)

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)

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

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.

Start the MCP server:

harbor-ferry-mcp

Available MCP Tools:

• list_ferries - List all known Boston Harbor ferries
• get_ferry_routes - Get route information
• track_ferry - Track specific ferry by MMSI
• track_all_ferries - Get all ferry positions
• clear_cache - Clear cached data

Claude Desktop Configuration

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "boston-harbor-ferries": {
      "command": "uvx",
      "args": ["--from", "/path/to/boston_harbor_ferries", "harbor-ferry-mcp"],
      "env": {
        "APRS_API_KEY": "your-api-key-here"
      }
    }
  }
}

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.