AI ASSISTANTS

VesselAPI MCP Server

An MCP (Model Context Protocol) server that connects Claude Desktop, Claude Code, Cursor, Windsurf and other MCP clients to the VesselAPI REST API. The assistant gets 19 tools for vessel search, positions, ETAs, port events and emissions, and answers questions about ships from current data.

Get a free API key vesselapi-mcp on npm

Tools

npx

No installation step

Node 18+

Runtime

MIT

Source on GitHub

How the server works

The server runs on your machine as a child process of the MCP client. The client starts it with npx -y vesselapi-mcp, passes your API key in the environment, and lists the 19 tools to the model. When the model calls a tool, the server makes one request to api.vesselapi.com and returns the JSON response.

Each tool call is one API request against your key's quota. List tools return one page at a time, with a nextToken for the next page, so the model fetches more only when it needs more. The free tier covers 150 calls a month, which is enough to try the server on real questions; the pricing page lists the paid tiers.

Positions are the latest stored AIS position for the vessel, with its timestamp. The ETA tools return the ETA the vessel last reported, which is a declared figure and not a prediction. The emissions and casualty tools return the records held for the vessel.

Setup

An API key from the dashboard is the only prerequisite. The free tier needs no card.

Claude Desktop, Cursor and Windsurf

Add this block to the client's MCP configuration file and restart the client.

{
  "mcpServers": {
    "vesselapi": {
      "command": "npx",
      "args": ["-y", "vesselapi-mcp"],
      "env": {
        "VESSELAPI_API_KEY": "your-api-key"
      }
    }
  }
}

Client	Configuration file
Claude Desktop	`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `%APPDATA%\Claude\claude_desktop_config.json` on Windows
Cursor	`.cursor/mcp.json` in the project, or `~/.cursor/mcp.json` for all projects
Windsurf	`~/.codeium/windsurf/mcp_config.json`

Claude Code

One command registers the server. Without --scope user it is written to .mcp.json in the current project.

claude mcp add vesselapi -e VESSELAPI_API_KEY=your-api-key -- npx -y vesselapi-mcp

Questions to try

"Where is the vessel with IMO 9811000 now, and when did it last report?" (calls get_vessel_position)
"Which vessels are within 20 km of Rotterdam?" (calls get_vessels_in_radius)
"List the arrivals at NLRTM since 06:00 today." (calls get_port_events)

The 19 tools

Vessels

search_vessels: Search by name, IMO, MMSI, flag, type, callsign or year built
get_vessel: Vessel particulars
get_vessel_position: Latest stored position: latitude, longitude, speed, heading and timestamp
get_vessel_positions_batch: Positions for several vessels in one call, with an optional time range
get_vessel_eta: The ETA and destination the vessel last reported
get_vessel_emissions: EU MRV emissions reports: CO2 and fuel consumption
get_vessel_casualties: Marine casualty records

Ports and port events

search_ports: Search by name, country, type, size, region, harbour size or harbour use
get_port: Port details by UN/LOCODE
get_port_inbound: Vessels reporting the port as their destination, within an ETA window
get_port_events: Arrivals and departures at a port (the last 2 hours unless timeFrom is given)
get_port_events_by_vessel: Port events for one vessel
get_vessel_last_port_event: The most recent port event for a vessel
list_port_events: Port events across all covered ports, filtered by time, country, port, vessel or event type
search_port_events_by_port: Port events by port name
search_port_events_by_vessel: Port events by vessel name

Emissions and location

list_emissions: EU MRV emissions reports, with an optional reporting-year filter
get_vessels_in_area: Vessels with a position inside a bounding box (default last 2 hours, at most 4 hours)
get_vessels_in_radius: Vessels with a position within a radius of a point (default last 2 hours, at most 4 hours)

The same endpoints are available directly through the Python, TypeScript and Go SDKs and in the API reference. Endpoint guides are in the documentation.

Connect an assistant to live ship data

A free API key covers 150 calls a month. The server is one line of configuration.

Get a free API key View pricing