# VesselAPI MCP Server

[![CI](https://github.com/vessel-api/vesselapi-mcp/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/vessel-api/vesselapi-mcp/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/vesselapi-mcp.svg)](https://www.npmjs.com/package/vesselapi-mcp)
[![Node](https://img.shields.io/node/v/vesselapi-mcp.svg)](https://www.npmjs.com/package/vesselapi-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

<a href="https://glama.ai/mcp/servers/vessel-api/vesselapi-mcp">
  <img width="380" height="200" src="https://glama.ai/mcp/servers/vessel-api/vesselapi-mcp/badge" />
</a>

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that exposes maritime data from the [VesselAPI](https://vesselapi.com) to AI assistants like Claude Desktop, Cursor, Windsurf, and Claude Code.

Server page: [vesselapi.com/mcp-server](https://vesselapi.com/mcp-server)

## Prerequisites

1. Sign up at [dashboard.vesselapi.com](https://dashboard.vesselapi.com)
2. Create an API token in your dashboard
3. Use the token as `VESSELAPI_API_KEY` in the configuration below

**Resources**: [Documentation](https://vesselapi.com/docs) | [API Explorer](https://vesselapi.com/api-reference) | [Dashboard](https://dashboard.vesselapi.com) | [Contact Support](mailto:support@vesselapi.com)

## Features

- **19 tools** covering vessels, ports, location search, and emissions
- Vessel search, positions (single and batch), ETA, emissions, and casualties
- Port search, details, port events (arrivals/departures), and port event search across all covered ports
- Geographic vessel search (bounding box and radius)
- Manual pagination to control API quota usage

## Quick Start

No installation required. Configure your AI client with `npx`:

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

## Configuration

Add the JSON above to the config file for your client:

| Client | Config file |
|---|---|
| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows) |
| Cursor | `.cursor/mcp.json` or `~/.cursor/mcp.json` |
| Claude Code | `claude mcp add`, which writes `.mcp.json` in the project or `~/.claude.json` for user scope |
| Windsurf | `~/.codeium/windsurf/mcp_config.json` |

## Tools

### Vessel Tools

| Tool | Description |
|---|---|
| `search_vessels` | Search vessels by name, IMO, MMSI, flag, type, callsign, or year built |
| `get_vessel` | Get detailed vessel information |
| `get_vessel_position` | Get the latest stored vessel position (lat/lon, speed, heading, timestamp); it may be hours or days old |
| `get_vessel_eta` | Get the ETA the vessel last reported (declared, not predicted) |
| `get_vessel_emissions` | Get EU MRV emissions reports (CO2, fuel consumption) |
| `get_vessel_casualties` | Get marine casualty records |
| `get_vessel_positions_batch` | Get positions for multiple vessels at once (with optional time range) |

### Port Tools

| Tool | Description |
|---|---|
| `search_ports` | Search ports by name, country, type, size, region, harbor size, or harbor use |
| `get_port` | Get port details by UN/LOCODE |
| `get_port_inbound` | Get vessels reporting a port as their destination, within an ETA window |
| `get_port_events` | Get arrivals/departures for a port (last 2 hours unless `timeFrom` is given) |
| `get_port_events_by_vessel` | Get port events for a vessel (last 2 hours unless `timeFrom` is given) |
| `list_port_events` | List port events across all covered ports, with filters for time, country, port, vessel, or event type |
| `search_port_events_by_port` | Search port events by port name |
| `search_port_events_by_vessel` | Search port events by vessel name |
| `get_vessel_last_port_event` | Get the most recent port event for a vessel |

### Emissions Tools

| Tool | Description |
|---|---|
| `list_emissions` | List EU MRV emissions reports, with an optional reporting-year filter |

### Location Tools

| Tool | Description |
|---|---|
| `get_vessels_in_area` | Find vessels with an AIS position in a bounding box (default last 2 hours, at most 4 hours) |
| `get_vessels_in_radius` | Find vessels with an AIS position within a radius of a point (default last 2 hours, at most 4 hours) |


## Pagination

All list endpoints support `limit` and `nextToken` parameters for manual pagination. When more results exist, the response includes a `nextToken`. Pass it in the next call to get the next page.

## Development

```bash
git clone https://github.com/vessel-api/vesselapi-mcp.git
cd vesselapi-mcp
npm install
npm run build
```

```bash
npm run build        # Build the server
npm run typecheck    # Type-check without emitting
npm run clean        # Remove build artifacts
```

### Testing with MCP Inspector

```bash
VESSELAPI_API_KEY=your-key npx @modelcontextprotocol/inspector node dist/index.js
```

## Attribution

Data attribution is listed at https://vesselapi.com/disclaimer#sources.

## License

MIT