marine-traffic-mcp by salmangada - MCP Server

Marine Traffic MCP Server

A Model Context Protocol (MCP) server implementation for accessing Marine Traffic vessel tracking data. This server provides real-time vessel position tracking, detailed vessel information, vessel search capabilities, and area-based vessel queries.

Features

Core Vessel Tracking

Get Vessel Position: Retrieve current position data for vessels by MMSI, IMO, or Ship ID
Get Vessel Details: Access comprehensive vessel information including specifications, destination, and port data
Search Vessels: Search for vessels by name, MMSI, or IMO number
Area-Based Queries: Get all vessels within a specified geographic bounding box

Historical & Voyage Data

Historical Track: Access vessel movement history over time (up to 30 days)
Port Calls: Get complete port call history including arrivals and departures (up to 1 year)
Vessel ETA: Retrieve estimated time of arrival with distance and speed calculations
Vessel Events: Get timeline of vessel activities and notable events

Port Intelligence

Port Details: Get comprehensive information about specific ports
Port Search: Search for ports by name or country

Proximity & Discovery

Nearby Vessels: Find all vessels within a radius of any location

Prerequisites

Go 1.21 or higher
Marine Traffic API key (Get one here)

Installation

Clone the repository:

git clone <repository-url>
cd marine-traffic-mcp

Install dependencies:

go mod download

Configure your API key:

cp .env.example .env
# Edit .env and add your Marine Traffic API key

Build the server:

go build -o marine-traffic-mcp

Configuration

The server is configured through environment variables. Create a .env file in the project root:

# Required: Your Marine Traffic API key
MARINE_TRAFFIC_API_KEY=your_api_key_here

# Optional: Override the default base URL
MARINE_TRAFFIC_BASE_URL=https://services.marinetraffic.com/api

# Optional: Enable debug mode for verbose logging
DEBUG=true

Environment Variables

Variable	Required	Default	Description
`MARINE_TRAFFIC_API_KEY`	Yes	-	Your Marine Traffic API key
`MARINE_TRAFFIC_BASE_URL`	No	`https://services.marinetraffic.com/api`	API base URL
`DEBUG`	No	`false`	Enable debug logging

Usage

Running the Server

./marine-traffic-mcp

Or with environment variables directly:

MARINE_TRAFFIC_API_KEY=your_key ./marine-traffic-mcp

MCP Tools

The server exposes 10 comprehensive MCP tools organized by category:

Core Vessel Tracking Tools

1. get_vessel_position

Get the current position of a vessel.

Parameters:

vessel_id (string, required): The vessel identifier
id_type (string, required): Type of identifier - mmsi, imo, or shipid

Example:

{
  "vessel_id": "371234000",
  "id_type": "mmsi"
}

Response:

{
  "mmsi": "371234000",
  "imo": "9123456",
  "ship_id": "123456",
  "lat": 37.7749,
  "lon": -122.4194,
  "speed": 12.5,
  "heading": 180,
  "course": 175,
  "status": "Under way using engine",
  "timestamp": "2025-12-05T10:30:00",
  "ship_name": "EXAMPLE VESSEL",
  "ship_type": "Cargo",
  "call_sign": "ABCD"
}

2. get_vessel_detail

Get detailed information about a vessel.

Parameters:

vessel_id (string, required): The vessel identifier
id_type (string, required): Type of identifier - mmsi, imo, or shipid

Example:

{
  "vessel_id": "9123456",
  "id_type": "imo"
}

Response:

{
  "mmsi": "371234000",
  "imo": "9123456",
  "ship_id": "123456",
  "ship_name": "EXAMPLE VESSEL",
  "ship_type": "Cargo",
  "flag": "US",
  "breadth": 32,
  "length": 225,
  "draught": 12.5,
  "deadweight": 45000,
  "gross_tonnage": 30000,
  "year_built": 2015,
  "call_sign": "ABCD",
  "destination": "LOS ANGELES",
  "eta": "2025-12-06T14:00:00",
  "current_port": "SAN FRANCISCO",
  "last_port": "SEATTLE",
  "last_port_time": "2025-12-04T08:00:00",
  "current_port_id": 3489
}

3. search_vessel

Search for vessels by name, MMSI, or IMO.

Parameters:

query (string, required): Search query
search_type (string, required): Type of search - name, mmsi, or imo

Example:

{
  "query": "MAERSK",
  "search_type": "name"
}

Response:

[
  {
    "mmsi": "219001234",
    "imo": "9321456",
    "ship_id": "234567",
    "ship_name": "MAERSK EXAMPLE",
    "ship_type": "Container Ship",
    "flag": "DK"
  },
  {
    "mmsi": "219005678",
    "imo": "9456789",
    "ship_id": "345678",
    "ship_name": "MAERSK SAMPLE",
    "ship_type": "Container Ship",
    "flag": "DK"
  }
]

4. get_vessels_in_area

Get all vessels within a geographic bounding box.

Parameters:

min_lat (number, required): Minimum latitude (south boundary)
max_lat (number, required): Maximum latitude (north boundary)
min_lon (number, required): Minimum longitude (west boundary)
max_lon (number, required): Maximum longitude (east boundary)

Example:

{
  "min_lat": 37.0,
  "max_lat": 38.0,
  "min_lon": -123.0,
  "max_lon": -122.0
}

Response:

[
  {
    "mmsi": "371234000",
    "imo": "9123456",
    "ship_id": "123456",
    "lat": 37.7749,
    "lon": -122.4194,
    "speed": 12.5,
    "heading": 180,
    "course": 175,
    "status": "Under way using engine",
    "timestamp": "2025-12-05T10:30:00",
    "ship_name": "EXAMPLE VESSEL",
    "ship_type": "Cargo",
    "call_sign": "ABCD"
  }
]

Historical & Voyage Tracking Tools

5. get_vessel_historical_track

Get historical position data for a vessel over time.

Parameters:

vessel_id (string, required): The vessel identifier
id_type (string, required): Type of identifier - mmsi, imo, or shipid
days (number, optional): Number of days of history (1-30, default: 3)

Example:

{
  "vessel_id": "371234000",
  "id_type": "mmsi",
  "days": 7
}

Response:

[
  {
    "mmsi": "371234000",
    "status": "Under way using engine",
    "speed": 12.5,
    "lon": -122.4194,
    "lat": 37.7749,
    "course": 175,
    "heading": 180,
    "timestamp": "2025-12-05T10:30:00",
    "ship_id": "123456"
  }
]

6. get_port_calls

Get port call history for a vessel including arrivals and departures.

Parameters:

vessel_id (string, required): The vessel identifier
id_type (string, required): Type of identifier - mmsi, imo, or shipid
days (number, optional): Number of days of history (1-365, default: 30)

Example:

{
  "vessel_id": "9123456",
  "id_type": "imo",
  "days": 90
}

Response:

[
  {
    "mmsi": "371234000",
    "imo": "9123456",
    "ship_name": "EXAMPLE VESSEL",
    "port_id": 3489,
    "port_name": "SAN FRANCISCO",
    "country_code": "US",
    "arrival": "2025-12-01T08:00:00",
    "departure": "2025-12-03T14:00:00",
    "time_at_port": 54,
    "last_port_id": 2985,
    "last_port_name": "SEATTLE",
    "next_port_id": 1234,
    "next_port_name": "LOS ANGELES"
  }
]

7. get_vessel_eta

Get estimated time of arrival with distance and speed calculations.

Parameters:

vessel_id (string, required): The vessel identifier
id_type (string, required): Type of identifier - mmsi, imo, or shipid

Example:

{
  "vessel_id": "371234000",
  "id_type": "mmsi"
}

Response:

{
  "mmsi": "371234000",
  "imo": "9123456",
  "ship_name": "EXAMPLE VESSEL",
  "destination_port": "LOS ANGELES",
  "port_id": 1234,
  "eta": "2025-12-06T14:00:00",
  "distance": 245.5,
  "remaining_time": 18,
  "average_speed": 13.6,
  "current_speed": 12.5
}

8. get_vessel_events

Get timeline of recent events and activities for a vessel.

Parameters:

vessel_id (string, required): The vessel identifier
id_type (string, required): Type of identifier - mmsi, imo, or shipid
days (number, optional): Number of days of history (1-90, default: 7)

Example:

{
  "vessel_id": "371234000",
  "id_type": "mmsi",
  "days": 14
}

Response:

[
  {
    "mmsi": "371234000",
    "imo": "9123456",
    "ship_name": "EXAMPLE VESSEL",
    "event_type": "PORT_ARRIVAL",
    "event_time": "2025-12-01T08:00:00",
    "port_id": 3489,
    "port_name": "SAN FRANCISCO",
    "location": "San Francisco Bay",
    "description": "Vessel arrived at port"
  }
]

Port Intelligence Tools

9. get_port_details

Get detailed information about a specific port.

Parameters:

port_id (number, required): The unique port identifier

Example:

{
  "port_id": 3489
}

Response:

{
  "port_id": 3489,
  "port_name": "SAN FRANCISCO",
  "country_code": "US",
  "country": "United States",
  "lat": 37.7749,
  "lon": -122.4194,
  "map_url": "https://marinetraffic.com/port/3489",
  "vessel_count": 42
}

10. search_port

Search for ports by name or country.

Parameters:

query (string, required): Search query (port name or country name)
search_type (string, required): Type of search - name or country

Example:

{
  "query": "Singapore",
  "search_type": "name"
}

Response:

[
  {
    "port_id": 3369,
    "port_name": "SINGAPORE",
    "country_code": "SG",
    "country": "Singapore",
    "lat": 1.2652,
    "lon": 103.8516,
    "vessel_count": 156
  }
]

Proximity & Discovery Tools

11. get_nearby_vessels

Find all vessels within a radius of a specific location.

Parameters:

latitude (number, required): Center point latitude
longitude (number, required): Center point longitude
radius (number, optional): Search radius in nautical miles (0.1-100, default: 5)

Example:

{
  "latitude": 37.7749,
  "longitude": -122.4194,
  "radius": 10
}

Response:

[
  {
    "mmsi": "371234000",
    "imo": "9123456",
    "ship_name": "EXAMPLE VESSEL",
    "ship_type": "Cargo",
    "lat": 37.7850,
    "lon": -122.4100,
    "distance": 1.2,
    "speed": 8.5,
    "heading": 175,
    "status": "Under way using engine",
    "timestamp": "2025-12-05T10:30:00"
  }
]

Project Structure

marine-traffic-mcp/
├── client/              # Marine Traffic API client
│   ├── client.go       # HTTP client and API methods
│   └── types.go        # Data type definitions
├── config/             # Configuration management
│   └── config.go       # Environment variable handling
├── server/             # MCP server implementation
│   └── server.go       # MCP protocol handlers
├── main.go             # Application entry point
├── go.mod              # Go module definition
├── .env.example        # Example environment configuration
├── .gitignore         # Git ignore rules
└── README.md          # This file

Architecture

The server follows a clean, extensible architecture:

Configuration Layer (config/): Handles environment variable loading and validation
Client Layer (client/): Encapsulates all Marine Traffic API interactions
Server Layer (server/): Implements MCP protocol and tool handlers
Main Entry Point (main.go): Wires everything together

Extensibility

To add new tools:

Add new API methods to client/client.go
Define response types in client/types.go
Register the tool in server/server.go using registerTools()
Implement the handler function following the pattern in existing handlers

Error Handling

The server implements comprehensive error handling:

Configuration errors: Logged and cause immediate exit
API errors: Returned as MCP error responses with detailed messages
Network errors: Wrapped with context and returned to the client
Validation errors: Checked at the MCP tool handler level

Security

API Key Management

API keys are loaded from environment variables only
Never hardcode API keys in source code
The .env file is excluded from version control via .gitignore
Keys are passed securely through HTTP query parameters (HTTPS recommended)

Best Practices

Always use HTTPS for API communication (default)
Store API keys in .env file or secure environment variable storage
Never commit .env file to version control
Rotate API keys regularly
Use restricted API keys with minimum required permissions

Development

Running in Debug Mode

Enable debug mode to see detailed request/response information:

DEBUG=true ./marine-traffic-mcp

Testing Tools Manually

You can test the tools using any MCP client or the Claude Desktop app.

API Rate Limits

Marine Traffic API enforces rate limits. The typical limit is:

200 requests per minute

Exceeding this limit results in HTTP 429 (Too Many Requests) responses. Implement appropriate rate limiting in production use.

License

[Your License Here]

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues related to:

This MCP server: Open an issue in this repository
Marine Traffic API: Contact Marine Traffic Support
MCP Protocol: Visit MCP Documentation

Acknowledgments

Built with mcp-go
Marine Traffic data provided by MarineTraffic.com