# 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/vessel-api-mcp-server">
  <img width="380" height="200" src="https://glama.ai/mcp/servers/@vessel-api/vessel-api-mcp-server/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.

## 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 global port event search
- Geographic vessel search (bounding box and radius)
- Manual pagination to control API quota usage

## Hosted deployment

A hosted deployment is available on [Fronteir AI](https://fronteir.ai/mcp/vessel-api-vesselapi-mcp).

## 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 current vessel position (lat/lon, speed, heading) |
| `get_vessel_eta` | Get vessel estimated time of arrival |
| `get_vessel_emissions` | Get emissions data (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 inbound to a port within an ETA window |
| `get_port_events` | Get arrivals/departures for a port |
| `get_port_events_by_vessel` | Get port events for a vessel |
| `list_port_events` | List port events globally 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 global vessel emissions data with optional year filter |

### Location Tools

| Tool | Description |
|---|---|
| `get_vessels_in_area` | Find vessels in a bounding box (with optional time range) |
| `get_vessels_in_radius` | Find vessels within a radius of a point (with optional time range) |


## 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
```

## Data Sources & Attribution

Emissions and casualty data: © European Union. Source: European Maritime Safety Agency
(EMSA): THETIS-MRV (EU MRV, Regulation (EU) 2015/757) and the European Marine Casualty
Information Platform (EMCIP). Reused under the European Commission reuse notice
(Commission Decision 2011/833/EU), which authorises reuse for commercial and
non-commercial purposes with acknowledgement of the source. Data may be transformed and
combined; EMSA does not endorse this service.

## License

MIT