Developer Tools

Official client libraries and AI integration tools for VesselAPI. Connect AI assistants to live maritime data via the MCP server, or integrate directly using our SDKs for TypeScript, Python, and Go.

MCP Server (AI Integration)

The VesselAPI MCP (Model Context Protocol) server enables AI assistants to query live maritime data directly. It works with Claude Desktop, Cursor, Claude Code, Windsurf, and any other MCP-compatible client.

The server exposes 24 tools covering vessel search, tracking, positions (single and batch), ETA, classification, ownership, emissions, inspections, casualties, port lookup, inbound vessels, port events, area-based vessel queries, and NAVTEX messages.

Installation

npx -y vesselapi-mcp
vesselapi-mcp on npm

Configuration

Add the following to your MCP client configuration:

Claude Desktop / Cursor / Claude Code

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

Configuration file locations:
Claude Desktop: claude_desktop_config.json
Cursor: .cursor/mcp.json
Claude Code: .claude/settings.json
Windsurf: ~/.codeium/windsurf/mcp_config.json

Available Tools

Tool Description
search_vessels Search vessels by name, callsign, flag, or type
get_vessel Get vessel details by MMSI or IMO
get_vessel_position Get current vessel position
get_vessel_positions_batch Get position history for multiple vessels
get_vessel_eta Get vessel ETA and destination
get_vessel_classification Get classification records
get_vessel_ownership Get ownership and management info
get_vessel_emissions Get emissions data
list_emissions List emissions records across the fleet by reporting year
get_vessel_inspections Get port state control inspections
get_vessel_inspection_detail Get full detail of one inspection, including deficiencies
get_vessel_casualties Get marine casualty records
search_ports Search ports by name or location
get_port Get port details by UN/LOCODE
get_port_inbound List vessels inbound to a port by reported ETA
get_port_events Get arrivals and departures at a port
list_port_events List port events globally with filters
search_port_events_by_port Search port events by port name
get_port_events_by_vessel Get port call history for a vessel
search_port_events_by_vessel Search port events by vessel name
get_vessel_last_port_event Get a vessel's most recent port call
get_vessels_in_area Find vessels in a bounding box
get_vessels_in_radius Find vessels within a radius
get_navtex_messages Get maritime safety messages

SDKs

All SDKs provide 38 methods across 7 service areas (vessels, ports, port events, emissions, search, location queries, and NAVTEX), each list method also having an auto-paginating variant. They share common features including auto-pagination, typed error handling, and automatic retry with exponential backoff.

Notifications API: the SDKs do not yet cover the Notifications API; support is coming. Until then, use plain HTTP for notifications: the surface is small and the docs include ready-to-use cURL, JavaScript, Python, and Java examples.

TypeScript / Node.js

vesselapi

Zero-dependency client for Node.js 18+. Uses native fetch.

Installation

npm install vesselapi
vesselapi on npm

Quick Start

import { VesselClient } from "vesselapi";

const client = new VesselClient("YOUR_API_KEY");

// Get vessel position
const { vesselPosition } = await client.vessels.position("253041000", { filterIdType: "mmsi" });
console.log(vesselPosition.latitude, vesselPosition.longitude);

// Search vessels with auto-pagination
for await (const vessel of client.search.allVessels({ filterName: "EVERGREEN" })) {
  console.log(vessel.name, vessel.mmsi);
}

Python

vessel-api-python

Sync and async clients for Python 3.9+. Built on httpx and pydantic.

Installation

pip install vessel-api-python
vessel-api-python on PyPI

Quick Start

from vessel_api_python import VesselClient

client = VesselClient(api_key="YOUR_API_KEY")

# Get vessel position
pos = client.vessels.position("253041000", filter_id_type="mmsi").vessel_position
print(pos.latitude, pos.longitude)

# Async usage
from vessel_api_python import AsyncVesselClient

async with AsyncVesselClient(api_key="YOUR_API_KEY") as client:
    resp = await client.vessels.position("253041000", filter_id_type="mmsi")

Go

vesselapi-go

Idiomatic Go client using functional options pattern. Go 1.22+.

Installation

go get github.com/vessel-api/vesselapi-go/v3
vesselapi-go on pkg.go.dev

Quick Start

package main

import (
    "context"
    "fmt"
    vesselapi "github.com/vessel-api/vesselapi-go/v3"
)

func main() {
    client := vesselapi.NewClient("YOUR_API_KEY")

    // Get vessel position
    pos, err := client.Vessels.Position(context.Background(), 253041000, "mmsi")
    if err != nil {
        panic(err)
    }
    fmt.Printf("%.4f, %.4f\n", pos.Latitude, pos.Longitude)
}

Common SDK Features

Auto-Pagination

Iterate over all results without managing pagination tokens. Each SDK provides language-native iterators (async iterators in TS, generators in Python, Iterator pattern in Go).

Typed Errors

Structured error types with helpers like isNotFound(), isRateLimited(), and isAuthError() for clean error handling.

Automatic Retries

Exponential backoff with jitter on 429 and 5xx errors. Respects Retry-After headers. Configurable max retries.

Environment Variables

Set VESSELAPI_API_KEY to avoid passing the key in code. All SDKs read this automatically.

Ready to Start Building?

Sign up for an API key and start integrating maritime data with your preferred language or AI assistant.

Get Your API Key Open API Explorer

Related Documentation

Vessel Tracking

Get vessel positions and details.

API Overview

Authentication, rate limits, and error handling.