Vessel Traffic MCP

Vessel tracking and shipping schedules for AI agents.

Vessel Traffic MCP is a read-only Model Context Protocol (MCP) server for vessel identity lookup, AIS-style positions, tracks, port calls, carrier schedules, vessel schedules, and delay heuristics. It gives Claude, ChatGPT, Codex, MCP Inspector, and other MCP clients one normalized maritime-data tool surface.

Use it when an agent needs to:

• search/fetch vessel context through generic connector-style MCP tools;
• resolve a vessel from a name, MMSI, IMO, callsign, or bill-of-lading text;
• ask where a vessel is, where it has been, or which vessels are in an area;
• search container-shipping schedules by port pair or vessel;
• return the original provider and source URL with every live/public result;
• test maritime workflows safely before buying paid AIS or schedule APIs.

The project does not bypass provider terms, paywalls, CAPTCHA, or access controls. Commercial providers are Bring Your Own Key (BYOK), the default test path is fixture-only, and this is not a navigation product.

Open source under the MIT license. Pre-1.0; APIs and tool surfaces may change.

Contents

• Install In An MCP Client
• Agent Discovery Page
• What It Exposes
• Provider Model
• Help Spread
• From Source
• Remote HTTP Setup
• Current Distribution
• Star History
• Shared Reference

Install In An MCP Client

For Claude Desktop, Claude Code, Codex CLI, Cursor, VS Code, or any stdio MCP client, use the npm package:

{
  "mcpServers": {
    "vessel-traffic-mcp": {
      "command": "npx",
      "args": ["-y", "@tools-mcp/vessel-traffic-mcp"],
      "env": {
        "VESSEL_MCP_TRANSPORT": "stdio",
        "VESSEL_MCP_ENABLE_PUBLIC_PROVIDERS": "myshiptracking,tradlinx"
      }
    }
  }
}

Then restart the client and try:

Find the current position of EVER GIVEN. Include source.provider and source.landingUrl.
Search carrier schedules from KRPUS to NLRTM. Include the source URL.

Full client setup lives in docs/runbooks/clients.md, and Codex details live in docs/runbooks/codex.md. Source-checkout config snippets are in Shared MCP Config Snippets. Marketplace and AI-client submission helpers live in llms-install.md, LAUNCHGUIDE.md, and assets/logo-400.png.

Agent Discovery Page

The public landing page for assistant-agent search and install snippets is:

https://tools-mcp.github.io/vessel-traffic-mcp/

Use that URL when sharing the project as a vessel AIS MCP, ship tracking MCP, ChatGPT MCP, Codex MCP, Claude MCP, or Gemini MCP server. The page includes a golden prompt for the EVER GIVEN scenario and client snippets for local stdio and remote Streamable HTTP setup.

Assistant services do not automatically discover arbitrary MCP servers. The operator must connect this MCP first; after that, the tool descriptions, search/fetch wrappers, and vessel-specific tools give the agent a clear path from a ship-name prompt to source-attributed results.

What It Exposes

Every live or public-provider response must expose provenance: source.provider and source.landingUrl. The project is designed to route users back to the original service, not to hide or rebrand the data source.

Provider Model

Use the provider_onboarding MCP tool to inspect provider signup URLs, required env vars, configured profile status, and validation steps. It is read-only and never creates accounts, accepts terms, solves CAPTCHA, completes email verification, sets payment details, or issues API keys.

Help Spread

If this could help someone building MCP tools, shipping/logistics software, or AI workflows around maritime data, share the repository and ask for real workflow feedback. A copy/paste sharing kit lives in docs/marketing/help-us-spread.md.

Useful help includes trying the npm install, posting a tailored community write-up, requesting a provider adapter, or explaining a real forwarding, trade, port-call, vessel ETA, or carrier-schedule workflow.

From Source

git clone https://github.com/tools-mcp/vessel-traffic-mcp.git
cd vessel-traffic-mcp
npm ci
npm run lint
npm test
npm run build
VESSEL_MCP_TRANSPORT=stdio \
VESSEL_MCP_ENABLE_PUBLIC_PROVIDERS=myshiptracking,tradlinx \
npm start

The default verification gate uses sanitized fixtures only. It does not call paid or live providers and does not require API keys, accounts, or network access.

For a local visual check with ship-name input and a map:

npm run start:map

Open http://127.0.0.1:8787 and search EVER GIVEN or MMSI 353136000.

Remote HTTP Setup

For remote MCP clients, run Streamable HTTP at /mcp with public /health:

export VESSEL_MCP_TRANSPORT=http
export VESSEL_MCP_HTTP_HOST=127.0.0.1
export VESSEL_MCP_HTTP_PORT=8765
export VESSEL_MCP_AUTH_TOKEN="<a-strong-random-token-you-generated>"
npm run start:http

curl -sf "http://127.0.0.1:8765/health"

MCP requests require Authorization: Bearer <token> when VESSEL_MCP_AUTH_TOKEN is set. See docs/runbooks/streamable-http-server.md and docs/runbooks/deployment-https.md.

Current Distribution

Launch copy and directory submission material live in docs/marketing.

Star History

Languages

• English
• 한국어
• 日本語
• 中文

Agent Prompt

Use this prompt when asking another coding agent to install the MCP:

Install and configure https://github.com/tools-mcp/vessel-traffic-mcp
as a local stdio MCP server on this machine.

Read README.md and llms.txt first. Clone the repository, run `npm ci`,
run `npm run build`, then add the MCP server to the local MCP client
using an absolute path to `dist/index.js`.

Use `VESSEL_MCP_TRANSPORT=stdio` and enable public providers with
`VESSEL_MCP_ENABLE_PUBLIC_PROVIDERS=myshiptracking,tradlinx`.

Do not commit local MCP client config files, env files, API keys,
cookies, HAR files, browser sessions, or raw captures. Do not copy
credentials from another machine.

After restarting the MCP client, verify with:
1. Ask for EVER GIVEN current position and include the source URL.
2. Ask for a KRPUS to NLRTM carrier schedule and include the source URL.

한국어

개요

vessel-traffic-mcp는 MCP 클라이언트가 허가된 해운/선박 데이터 소스를 읽기 전용 도구로 조회할 수 있게 해주는 서버입니다.

선박명, MMSI, IMO, 호출부호 기반 검색, 최신 위치 조회, 영역 조회, 항만 호출, 선사 스케줄, 선박별 스케줄, 스케줄 지연 판단을 제공합니다.

실시간 또는 공개 provider 응답은 반드시 source.provider와 source.landingUrl을 포함해야 합니다. 이 프로젝트의 목적은 원 서비스 유입과 출처 노출을 제공하는 것이며, 출처를 숨기거나 재브랜딩하는 것이 아닙니다.

공유를 도와줄 사람에게 보낼 짧은 문구와 커뮤니티용 글 초안은 docs/marketing/help-us-spread.md에 정리되어 있습니다.

빠른 시작

git clone https://github.com/tools-mcp/vessel-traffic-mcp.git
cd vessel-traffic-mcp
npm install
npm run lint
npm test
npm run build

기본 검증은 sanitize된 fixture만 사용합니다. 유료 provider나 live provider를 호출하지 않으며 API 키, 계정, 네트워크 접근이 필요하지 않습니다.

로컬 MCP 설정

로컬 데스크톱/CLI 클라이언트에서는 stdio transport를 사용합니다.

VESSEL_MCP_TRANSPORT=stdio npm start

Codex CLI, Claude Desktop, Claude Code 설정은 공통 MCP 설정 예시를 사용하면 됩니다. 전체 클라이언트 설정은 docs/runbooks/clients.md, Codex 전용 설정은 docs/runbooks/codex.md에 정리되어 있습니다.

원격 MCP 설정

원격 MCP 클라이언트는 Streamable HTTP /mcp 엔드포인트를 사용합니다. /health는 공개 health check입니다.

export VESSEL_MCP_TRANSPORT=http
export VESSEL_MCP_HTTP_HOST=127.0.0.1
export VESSEL_MCP_HTTP_PORT=8765
export VESSEL_MCP_AUTH_TOKEN="<a-strong-random-token-you-generated>"
npm run start:http

VESSEL_MCP_AUTH_TOKEN을 설정한 경우 MCP 요청에는 Authorization: Bearer <token>이 필요합니다. 배포 문서는 docs/runbooks/deployment-https.md를 참고하세요.

공개 Provider

브라우저 캡처 기반 공개 adapter는 명시적으로 켜야 합니다.

VESSEL_MCP_ENABLE_PUBLIC_PROVIDERS=myshiptracking,tradlinx npm start

• myshiptracking: 선박 자동완성, 선택 MMSI 기반 최신 위치, 지도 영역 조회.
• tradlinx: FCL/LCL 선사 스케줄 조회.
• shipfinder: 명시적 provider 라우팅용 선박 자동완성 및 상세 API 형태.

응답에는 항상 원 출처 provider와 사용자가 열 수 있는 출처 URL을 포함합니다.

BYOK Provider

유료/credential 기반 provider는 BYOK 방식으로만 사용합니다. 실제 키는 로그, 에러, MCP 응답에 노출되지 않습니다.

export VESSEL_MCP_PROFILE_MARINETRAFFIC__API_KEY="<your-key>"
export VESSEL_MCP_ENABLE_BYOK_PROVIDERS="marinetraffic,vesselfinder,aisstream,aishub,barentswatch,searates-schedules,routescanner-connect,vesselapi,datadocked,datalastic,globalfishingwatch"

현재 credential 기반으로 런타임 등록 가능한 provider는 marinetraffic, vesselfinder, aisstream, aishub, barentswatch, searates-schedules, routescanner-connect, vesselapi, datadocked, datalastic, globalfishingwatch입니다. 기본 credential profile이 설정된 provider는 자동으로 등록됩니다.

자세한 내용은 docs/runbooks/credential-profiles.md와 docs/runbooks/operator.md를 참고하세요.

provider_onboarding MCP 도구를 사용하면 provider별 가입 URL, 필요한 env var, 현재 credential 설정 여부, 검증 단계를 확인할 수 있습니다. 이 도구는 읽기 전용이며 계정 생성, 약관 동의, CAPTCHA, 이메일 인증, 결제 정보 설정, API 키 발급을 대신 수행하지 않습니다.

에이전트 설정 프롬프트

다른 코딩 에이전트에게 이 MCP를 설치하게 할 때 사용할 프롬프트입니다.

https://github.com/tools-mcp/vessel-traffic-mcp 를 이 머신의 로컬
stdio MCP 서버로 설치하고 설정해줘.

먼저 README.md와 llms.txt를 읽어라. repo를 clone하고 `npm ci`,
`npm run build`를 실행한 뒤, 로컬 MCP 클라이언트 설정에
`dist/index.js`의 절대경로를 등록해라.

`VESSEL_MCP_TRANSPORT=stdio`를 사용하고,
`VESSEL_MCP_ENABLE_PUBLIC_PROVIDERS=myshiptracking,tradlinx`를 설정해라.

로컬 MCP 클라이언트 설정 파일, env 파일, API 키, 쿠키, HAR 파일,
브라우저 세션, raw capture는 커밋하지 마라. 다른 머신의 credential을
복사하지 마라.

MCP 클라이언트를 재시작한 뒤 다음으로 검증해라:
1. EVER GIVEN 현재 위치를 조회하고 출처 URL을 함께 보여줘.
2. KRPUS에서 NLRTM까지의 선사 스케줄을 조회하고 출처 URL을 함께 보여줘.

日本語

概要

vessel-traffic-mcp は、MCP クライアントから許可された海事データ ソースを読み取り専用で参照するためのサーバーです。

船名、MMSI、IMO、コールサインによる検索、最新位置、エリア検索、 寄港情報、船会社スケジュール、船舶別スケジュール、遅延判定を 提供します。

ライブまたは公開 provider の応答では、source.provider と source.landingUrl を必ず含めます。このプロジェクトは元サービスへ ユーザーを誘導し、出典を明示することを目的としています。

クイックスタート

git clone https://github.com/tools-mcp/vessel-traffic-mcp.git
cd vessel-traffic-mcp
npm install
npm run lint
npm test
npm run build

標準の検証は sanitize 済み fixture のみを使います。有料 provider や live provider は呼び出さず、API キー、アカウント、ネットワーク接続も 不要です。

ローカル MCP 設定

ローカルのデスクトップ/CLI クライアントでは stdio transport を使います。

VESSEL_MCP_TRANSPORT=stdio npm start

Codex CLI、Claude Desktop、Claude Code の設定には 共通 MCP 設定例を使用してください。

リモート MCP 設定

リモート MCP クライアントでは Streamable HTTP の /mcp を使います。 /health は公開 health check です。

export VESSEL_MCP_TRANSPORT=http
export VESSEL_MCP_HTTP_HOST=127.0.0.1
export VESSEL_MCP_HTTP_PORT=8765
export VESSEL_MCP_AUTH_TOKEN="<a-strong-random-token-you-generated>"
npm run start:http

VESSEL_MCP_AUTH_TOKEN を設定した場合、MCP リクエストには Authorization: Bearer <token> が必要です。

公開 Provider

ブラウザキャプチャ由来の公開 adapter は明示的に有効化します。

VESSEL_MCP_ENABLE_PUBLIC_PROVIDERS=myshiptracking,tradlinx npm start

• myshiptracking: 船舶オートコンプリート、選択 MMSI からの最新位置、 地図範囲検索。
• tradlinx: FCL/LCL の船会社スケジュール検索。
• shipfinder: 明示的 provider ルーティング用の船舶検索と詳細 API 形状。

BYOK Provider

有料または credential が必要な provider は BYOK のみです。実際のキーは ログ、エラー、MCP 応答に出しません。

export VESSEL_MCP_PROFILE_MARINETRAFFIC__API_KEY="<your-key>"
export VESSEL_MCP_ENABLE_BYOK_PROVIDERS="marinetraffic,vesselfinder,aisstream,aishub,barentswatch,searates-schedules,routescanner-connect,vesselapi,datadocked,datalastic,globalfishingwatch"

現在 runtime で有効化できる credentialed provider は marinetraffic, vesselfinder, aisstream, aishub, barentswatch, searates-schedules, routescanner-connect, vesselapi, datadocked, datalastic, globalfishingwatch です。

エージェント設定プロンプト

別のコーディングエージェントに MCP を設定させる場合のプロンプトです。

https://github.com/tools-mcp/vessel-traffic-mcp を、このマシンの
ローカル stdio MCP サーバーとしてインストールして設定してください。

最初に README.md と llms.txt を読んでください。repo を clone し、
`npm ci` と `npm run build` を実行し、`dist/index.js` の絶対パスを
ローカル MCP クライアントに登録してください。

`VESSEL_MCP_TRANSPORT=stdio` を使い、
`VESSEL_MCP_ENABLE_PUBLIC_PROVIDERS=myshiptracking,tradlinx` を設定してください。

ローカル MCP クライアント設定、env ファイル、API キー、Cookie、HAR、
ブラウザセッション、raw capture を commit しないでください。他の
マシンから credential をコピーしないでください。

再起動後、EVER GIVEN の現在位置と出典 URL、KRPUS から NLRTM への
船会社スケジュールと出典 URL を確認してください。

中文

概览

vessel-traffic-mcp 是一个只读 MCP 服务器，让 MCP 客户端能够通过 统一工具接口访问已授权的海事数据来源。

它支持按船名、MMSI、IMO、呼号搜索船舶，查询最新位置、区域位置、 港口靠泊、承运人航线计划、船舶计划和延误判断。

所有实时或公开 provider 的响应都必须包含 source.provider 和 source.landingUrl。本项目用于向原始服务导流并明确显示出处，而不是 隐藏或重新包装数据来源。

快速开始

git clone https://github.com/tools-mcp/vessel-traffic-mcp.git
cd vessel-traffic-mcp
npm install
npm run lint
npm test
npm run build

默认验证只使用已清洗的 fixture，不调用付费或实时 provider，也不需要 API key、账号或网络访问。

本地 MCP 设置

本地桌面和 CLI 客户端使用 stdio transport。

VESSEL_MCP_TRANSPORT=stdio npm start

Codex CLI、Claude Desktop、Claude Code 可使用 共享 MCP 配置片段。

远程 MCP 设置

远程 MCP 客户端使用 Streamable HTTP /mcp，/health 是公开健康检查。

export VESSEL_MCP_TRANSPORT=http
export VESSEL_MCP_HTTP_HOST=127.0.0.1
export VESSEL_MCP_HTTP_PORT=8765
export VESSEL_MCP_AUTH_TOKEN="<a-strong-random-token-you-generated>"
npm run start:http

设置 VESSEL_MCP_AUTH_TOKEN 后，MCP 请求需要 Authorization: Bearer <token>。

公开 Provider

浏览器捕获得到的公开 adapter 需要显式启用。

VESSEL_MCP_ENABLE_PUBLIC_PROVIDERS=myshiptracking,tradlinx npm start

• myshiptracking: 船舶自动完成、按选定 MMSI 查询最新位置、地图范围查询。
• tradlinx: FCL/LCL 承运人航线计划查询。
• shipfinder: 用于显式 provider 路由的船舶搜索和详情 API 形状。

BYOK Provider

付费或需要 credential 的 provider 只能使用 BYOK。真实 key 不会出现在日志、 错误或 MCP 响应中。

export VESSEL_MCP_PROFILE_MARINETRAFFIC__API_KEY="<your-key>"
export VESSEL_MCP_ENABLE_BYOK_PROVIDERS="marinetraffic,vesselfinder,aisstream,aishub,barentswatch,searates-schedules,routescanner-connect,vesselapi,datadocked,datalastic,globalfishingwatch"

当前可在 runtime 启用的 credentialed provider 是 marinetraffic, vesselfinder, aisstream, aishub, barentswatch, searates-schedules, routescanner-connect, vesselapi, datadocked, datalastic, globalfishingwatch。

Agent 设置提示词

让其他编码 agent 安装此 MCP 时可使用以下提示词。

请将 https://github.com/tools-mcp/vessel-traffic-mcp 安装并配置为本机
本地 stdio MCP 服务器。

先阅读 README.md 和 llms.txt。clone 仓库，运行 `npm ci` 和
`npm run build`，然后在本地 MCP 客户端中用 `dist/index.js` 的绝对路径
注册服务器。

使用 `VESSEL_MCP_TRANSPORT=stdio`，并设置
`VESSEL_MCP_ENABLE_PUBLIC_PROVIDERS=myshiptracking,tradlinx`。

不要提交本地 MCP 客户端配置、env 文件、API key、cookie、HAR 文件、
浏览器 session 或 raw capture。不要从其他机器复制 credentials。

重启 MCP 客户端后验证：
1. 查询 EVER GIVEN 当前船位，并显示来源 URL。
2. 查询 KRPUS 到 NLRTM 的承运人航线计划，并显示来源 URL。

Shared Reference

Shared MCP Config Snippets

Codex CLI ~/.codex/config.toml:

[mcp_servers.vessel-traffic-mcp]
command = "node"
args = ["/absolute/path/to/vessel-traffic-mcp/dist/index.js"]

[mcp_servers.vessel-traffic-mcp.env]
VESSEL_MCP_TRANSPORT = "stdio"
VESSEL_MCP_ENABLE_PUBLIC_PROVIDERS = "myshiptracking,tradlinx"

Claude Desktop / Claude Code config:

{
  "mcpServers": {
    "vessel-traffic-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/vessel-traffic-mcp/dist/index.js"],
      "env": {
        "VESSEL_MCP_TRANSPORT": "stdio",
        "VESSEL_MCP_ENABLE_PUBLIC_PROVIDERS": "myshiptracking,tradlinx"
      }
    }
  }
}

Provider Implementation Status

The PRD is intentionally broader than the adapters enabled by default. Current status:

The structured source of truth is config/provider-catalog.example.json and the human-readable inventory is docs/provider-catalog.md.

Local Vessel Map UI

For a local visual check with ship-name input and a map:

npm run start:map

Open http://127.0.0.1:8787 and search EVER GIVEN or MMSI 353136000. The UI displays a map marker and a visible source link.

Schedule Tools

Registered read-only schedule tools:

• carrier_schedule_search
• vessel_schedule
• schedule_delay_predict

Registered read-only provider/setup tools:

• provider_status
• data_sources
• credential_profiles
• provider_onboarding

Fixture-backed checks:

KRPUS에서 NLRTM으로 가는 선사 스케줄을 조회하고, 출처 URL도 같이 보여줘.
EVER GIVEN 선박 스케줄을 조회하고 ETA 지연 여부를 계산해줘.

Schedule-provider candidates are tracked in docs/provider-catalog.md. Tradelinx has an explicit opt-in carrier_schedule_search adapter backed by sanitized browser-captured endpoint shapes documented in docs/runbooks/schedule-api-capture-results.md.

Capture And Safety Boundary

This project does not aim to bypass commercial services. It supports:

• Official APIs and open-data feeds.
• User-provided API credentials and organization-level BYOK credential profiles for paid providers.
• Sanitized HAR/network samples from operator-owned, authorized browser sessions, only where allowed by service terms.

It must not store raw cookies, bearer tokens, API keys, private HAR files, raw captures, or private browser sessions in the repository. The full hard-rule list lives in AGENTS.md, and security expectations are in SECURITY.md.

Authorized capture tooling is documented in docs/runbooks/capture-execution.md. The sanitized import command is npm run capture:import, and traffic IR generation is npm run capture:ir.

Not for navigation. AIS data returned by configured providers may be delayed, incomplete, or inaccurate. This project is not a safety-critical navigation tool.

Project Layout

src/
  capture/      sanitized capture fixture importer + traffic IR CLI
  config/       credential profile loader, provider catalog
  providers/    adapter interfaces, registry, router, rate limit, TTL cache
  server/       MCP transports and tool handlers
  tools/        read-only tool definitions
  util/         structured logging and redaction helpers
test/           node:test deterministic tests; fixture-backed
docs/           PRD, TDD, provider catalog, and runbooks

Documentation

• llms.txt — compact agent-facing project brief.
• docs/index.html — static agent discovery page published through GitHub Pages.
• server.json — MCP Registry metadata for the io.github.tools-mcp/vessel-traffic-mcp namespace.
• AGENTS.md — project hard rules.
• CODE_OF_CONDUCT.md — collaboration expectations.
• docs/PRD.md — product requirements.
• docs/TDD.md — technical design.
• docs/provider-catalog.md — provider inventory and routing policy.
• docs/runbooks/operator.md — end-to-end operator runbook.
• docs/runbooks/clients.md — client setup for Claude Desktop, Claude Code, ChatGPT remote MCP, and MCP Inspector.
• docs/runbooks/codex.md — Codex CLI MCP wiring and Codex plugin metadata state.
• docs/runbooks/credential-profiles.md — BYOK profile handling.
• docs/runbooks/deployment-https.md — HTTPS deployment for the Streamable HTTP MCP endpoint.
• docs/runbooks/release-checklist.md — pre-release safety checklist.
• docs/runbooks/public-sharing.md — GitHub, MCP Registry, Smithery, Glama, PulseMCP, and launch-post sharing checklist.
• docs/runbooks/api-capture-reference-only.md — reference-only boundary for raw capture sessions.
• docs/runbooks/browser-api-capture-results.md — sanitized browser capture results for vessel APIs.
• docs/runbooks/schedule-api-capture-results.md — sanitized browser capture results for schedule APIs.
• docs/discoverability.md — package, repository, and documentation discoverability contract.

Topics

vessel-traffic-mcp is intended to be findable from MCP and plugin search surfaces. The same set is reflected in package.json keywords and suggested GitHub topics.

• vessel AIS MCP
• ship tracking MCP
• MarineTraffic MCP
• Claude MCP (Claude Desktop, Claude Code)
• ChatGPT MCP (ChatGPT remote MCP connector)
• Codex plugin (Codex / OpenAI plugin / marketplace workflows)
• Gemini MCP (Gemini CLI and Gemini Code Assist)
• MCP / Model Context Protocol server
• AIS / vessel tracking / ship tracking
• BYOK paid-provider routing (MarineTraffic, VesselFinder, AISStream, AISHub, BarentsWatch, SeaRates, Routescanner, VesselAPI, Data Docked, and other catalog entries)

Contributing

Contributions are welcome. Please read CONTRIBUTING.md first. The project has non-negotiable safety rules around credentials, capture fixtures, and the read-only contract.

Use GitHub Issues for bugs, provider requests, and authorized capture reviews. Use GitHub Discussions for roadmap, integration, and collaboration threads. The sharing checklist is in docs/runbooks/public-sharing.md.

Security

Do not file a public GitHub issue for a suspected vulnerability. See SECURITY.md for the private reporting channel.

License

MIT. See NOTICE for the not-for-navigation notice.