{ "markdown": "# Vessel Traffic MCP\n\n

\n English |\n 한국어 |\n 日本語 |\n 中文\n

\n\n

\n \"License:\n \"npm\"\n \"npm\n \"CI\"\n \"GitHub\n \"GitHub\n

\n\n

\n \"MCP\n \"Agent\n \"GitHub\n \"GitHub\n

\n\n**Vessel tracking and shipping schedules for AI agents.**\n\n

\n \"Local\n

\n\nVessel Traffic MCP is a read-only **Model Context Protocol (MCP) server**\nfor vessel identity lookup, AIS-style positions, tracks, port calls,\ncarrier schedules, vessel schedules, and delay heuristics. It gives\nClaude, ChatGPT, Codex, MCP Inspector, and other MCP clients one\nnormalized maritime-data tool surface.\n\nUse it when an agent needs to:\n\n- search/fetch vessel context through generic connector-style MCP tools;\n- resolve a vessel from a name, MMSI, IMO, callsign, or bill-of-lading text;\n- ask where a vessel is, where it has been, or which vessels are in an area;\n- search container-shipping schedules by port pair or vessel;\n- return the original provider and source URL with every live/public result;\n- test maritime workflows safely before buying paid AIS or schedule APIs.\n\nThe project does not bypass provider terms, paywalls, CAPTCHA, or access\ncontrols. Commercial providers are Bring Your Own Key (BYOK), the default\ntest path is fixture-only, and this is not a navigation product.\n\nOpen source under the [MIT license](./LICENSE). Pre-1.0; APIs and tool\nsurfaces may change.\n\n## Contents\n\n- [Install In An MCP Client](#install-in-an-mcp-client)\n- [Agent Discovery Page](#agent-discovery-page)\n- [What It Exposes](#what-it-exposes)\n- [Provider Model](#provider-model)\n- [Responsible Use And Third-Party Rights](#responsible-use-and-third-party-rights)\n- [Help Spread](#help-spread)\n- [From Source](#from-source)\n- [Remote HTTP Setup](#remote-http-setup)\n- [Current Distribution](#current-distribution)\n- [Star History](#star-history)\n- [Shared Reference](#shared-reference)\n\n## Install In An MCP Client\n\nFor Claude Desktop, Claude Code, Codex CLI, Cursor, VS Code, or any\nstdio MCP client, use the npm package:\n\n```json\n{\n \"mcpServers\": {\n \"vessel-traffic-mcp\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@tools-mcp/vessel-traffic-mcp\"],\n \"env\": {\n \"VESSEL_MCP_TRANSPORT\": \"stdio\",\n \"VESSEL_MCP_ENABLE_PUBLIC_PROVIDERS\": \"myshiptracking,tradlinx,aisfriends\"\n }\n }\n }\n}\n```\n\nThen restart the client and try:\n\n```text\nFind the current position of EVER GIVEN. Include source.provider and source.landingUrl.\nSearch carrier schedules from KRPUS to NLRTM. Include the source URL.\n```\n\nFull client setup lives in\n[`docs/runbooks/clients.md`](./docs/runbooks/clients.md), and Codex\ndetails live in [`docs/runbooks/codex.md`](./docs/runbooks/codex.md).\nSource-checkout config snippets are in\n[Shared MCP Config Snippets](#shared-mcp-config-snippets).\nMarketplace and AI-client submission helpers live in\n[`llms-install.md`](./llms-install.md), [`LAUNCHGUIDE.md`](./LAUNCHGUIDE.md),\nand [`assets/logo-400.png`](./assets/logo-400.png).\n\n## Agent Discovery Page\n\nThe public landing page for assistant-agent search and install snippets is:\n\nhttps://tools-mcp.github.io/vessel-traffic-mcp/\n\nUse that URL when sharing the project as a **vessel AIS MCP**, **ship tracking\nMCP**, **ChatGPT MCP**, **Codex MCP**, **Claude MCP**, or **Gemini MCP** server.\nThe page includes a golden prompt for the `EVER GIVEN` scenario and client\nsnippets for local stdio and remote Streamable HTTP setup.\n\nAssistant services do not automatically discover arbitrary MCP servers. The\noperator must connect this MCP first; after that, the tool descriptions,\n`search`/`fetch` wrappers, and vessel-specific tools give the agent a clear\npath from a ship-name prompt to source-attributed results.\n\n## What It Exposes\n\n| Area | Read-only tools |\n| --- | --- |\n| Search-style connector flow | `search`, `fetch` |\n| Vessel identity | `vessel_search`, `vessel_name_resolve`, `document_vessel_lookup` |\n| AIS-style movement | `vessel_position`, `vessel_area`, `vessel_track` |\n| Port activity | `port_calls` |\n| Shipping schedules | `carrier_schedule_search`, `vessel_schedule`, `schedule_delay_predict` |\n| Provider setup | `provider_status`, `data_sources`, `credential_profiles`, `provider_onboarding` |\n\nEvery live or public-provider response must expose provenance:\n`source.provider` and `source.landingUrl`. The project is designed to\nroute users back to the original service, not to hide or rebrand the\ndata source.\n\n## Provider Model\n\n| Provider group | How it is enabled | Notes |\n| --- | --- | --- |\n| Fixture | default | deterministic tests and demos; no network, accounts, or API keys |\n| Public opt-in | `VESSEL_MCP_ENABLE_PUBLIC_PROVIDERS=myshiptracking,tradlinx,aisfriends` | public web adapters with source attribution |\n| BYOK commercial/community APIs | `VESSEL_MCP_ENABLE_BYOK_PROVIDERS=...` plus `VESSEL_MCP_PROFILE_*` env vars | user-owned credentials only; secrets are redacted from logs, errors, and MCP responses |\n| Remote deployment | `VESSEL_MCP_TRANSPORT=http` | Streamable HTTP at `/mcp`; set `VESSEL_MCP_AUTH_TOKEN` for `Authorization: Bearer ` |\n\nUse the `provider_onboarding` MCP tool to inspect provider signup URLs,\nrequired env vars, configured profile status, and validation steps. It\nis read-only and never creates accounts, accepts terms, solves CAPTCHA,\ncompletes email verification, sets payment details, or issues API keys.\n\n## Responsible Use And Third-Party Rights\n\nThis project is provided as open-source infrastructure for public-interest\ninteroperability, workflow testing, and source-attributed maritime data access.\nIt does not grant any right to copy, redistribute, rebrand, bypass, or misuse\nthird-party services, databases, maps, trademarks, copyrighted material, API\nresponses, or provider content.\n\nUsers are responsible for how they configure and operate the software, including\ntheir compliance with applicable law, provider terms, account permissions,\nrate limits, data licenses, and internal company policies. Do not use this\nproject to bypass authentication, paywalls, CAPTCHA, access controls, robots\npolicies, or commercial restrictions.\n\nThe authors and contributors respect the rights and terms of all referenced\nservices and data providers. Live and public-provider responses are designed\nto preserve attribution through `source.provider` and `source.landingUrl` and\nto route users back to the original source. If a rights holder, service\noperator, or affected party reports a substantiated concern, the maintainers\nwill review it promptly and, where appropriate, modify, disable, or remove the\naffected adapter, documentation, fixture, or reference.\n\nThe software is provided under the MIT license, without warranty. Nothing in\nthis README is legal advice or a substitute for reviewing the terms that apply\nto your own use case.\n\n## Help Spread\n\nIf this could help someone building MCP tools, shipping/logistics software,\nor AI workflows around maritime data, share the repository and ask for real\nworkflow feedback. A copy/paste sharing kit lives in\n[`docs/marketing/help-us-spread.md`](./docs/marketing/help-us-spread.md).\n\nUseful help includes trying the npm install, posting a tailored community\nwrite-up, requesting a provider adapter, or explaining a real forwarding,\ntrade, port-call, vessel ETA, or carrier-schedule workflow.\n\n## From Source\n\n```bash\ngit clone https://github.com/tools-mcp/vessel-traffic-mcp.git\ncd vessel-traffic-mcp\nnpm ci\nnpm run lint\nnpm test\nnpm run build\nVESSEL_MCP_TRANSPORT=stdio \\\nVESSEL_MCP_ENABLE_PUBLIC_PROVIDERS=myshiptracking,tradlinx,aisfriends \\\nnpm start\n```\n\nThe default verification gate uses sanitized fixtures only. It does not\ncall paid or live providers and does not require API keys, accounts, or\nnetwork access.\n\nFor a local visual check with ship-name input and a map:\n\n```bash\nnpm run start:map\n```\n\nOpen `http://127.0.0.1:8787` and search `EVER GIVEN` or MMSI\n`353136000`.\n\n## Remote HTTP Setup\n\nFor remote MCP clients, run Streamable HTTP at `/mcp` with public\n`/health`:\n\n```bash\nexport VESSEL_MCP_TRANSPORT=http\nexport VESSEL_MCP_HTTP_HOST=127.0.0.1\nexport VESSEL_MCP_HTTP_PORT=8765\nexport VESSEL_MCP_AUTH_TOKEN=\"\"\nnpm run start:http\n\ncurl -sf \"http://127.0.0.1:8765/health\"\n```\n\nMCP requests require `Authorization: Bearer ` when\n`VESSEL_MCP_AUTH_TOKEN` is set. See\n[`docs/runbooks/streamable-http-server.md`](./docs/runbooks/streamable-http-server.md)\nand [`docs/runbooks/deployment-https.md`](./docs/runbooks/deployment-https.md).\n\n## Current Distribution\n\n| Surface | Status | Access |\n| --- | --- | --- |\n| GitHub | Public | https://github.com/tools-mcp/vessel-traffic-mcp |\n| Agent landing page | Public | https://tools-mcp.github.io/vessel-traffic-mcp/ |\n| npm | Public | `@tools-mcp/vessel-traffic-mcp@0.1.0` at https://www.npmjs.com/package/@tools-mcp/vessel-traffic-mcp |\n| GitHub Release | Published | https://github.com/tools-mcp/vessel-traffic-mcp/releases/tag/v0.1.0 |\n| MCP Registry | Published | `io.github.tools-mcp/vessel-traffic-mcp@0.1.0` in the [official registry](https://registry.modelcontextprotocol.io/?q=io.github.tools-mcp%2Fvessel-traffic-mcp) |\n| ServerHub | Listed | https://www.serverhub.digital/servers/vessel-traffic-mcp |\n| VaultPlane | Listed | https://www.vaultplane.com/server/vessel-traffic-mcp |\n| MCPRepository | Submitted | Queued for validation at https://mcprepository.com/tools-mcp/vessel-traffic-mcp |\n| Local map UI | Ready from source | `npm run start:map`, then open `http://127.0.0.1:8787` |\n| HTTP directory metadata | Ready from source | `npm run start:http`, then fetch `/.well-known/mcp/server-card.json` |\n| Glama | Submitted for review | Submitted through Glama's Add Server flow on 2026-05-27; public listing URL and score badge are reserved at https://glama.ai/mcp/servers/tools-mcp/vessel-traffic-mcp and may return 404 until review/indexing completes |\n| PulseMCP | Submission/indexing pending | Track in [`docs/runbooks/public-sharing.md`](./docs/runbooks/public-sharing.md) and [`docs/marketing/outreach-status.md`](./docs/marketing/outreach-status.md) |\n| Smithery | HTTPS endpoint pending | Needs a stable public HTTPS `/mcp` URL |\n\nLaunch copy and directory submission material live in\n[`docs/marketing`](./docs/marketing/launch-kit.md).\n\n## Star History\n\n[![Star History Chart](https://api.star-history.com/svg?repos=tools-mcp/vessel-traffic-mcp&type=Date)](https://www.star-history.com/#tools-mcp/vessel-traffic-mcp&Date)\n\n## Languages\n\n- [English](#install-in-an-mcp-client)\n- [한국어](#한국어)\n- [日本語](#日本語)\n- [中文](#中文)\n\n### Agent Prompt\n\nUse this prompt when asking another coding agent to install the MCP:\n\n```text\nInstall and configure https://github.com/tools-mcp/vessel-traffic-mcp\nas a local stdio MCP server on this machine.\n\nRead README.md and llms.txt first. Clone the repository, run `npm ci`,\nrun `npm run build`, then add the MCP server to the local MCP client\nusing an absolute path to `dist/index.js`.\n\nUse `VESSEL_MCP_TRANSPORT=stdio` and enable public providers with\n`VESSEL_MCP_ENABLE_PUBLIC_PROVIDERS=myshiptracking,tradlinx,aisfriends`.\n\nDo not commit local MCP client config files, env files, API keys,\ncookies, HAR files, browser sessions, or raw captures. Do not copy\ncredentials from another machine.\n\nAfter restarting the MCP client, verify with:\n1. Ask for EVER GIVEN current position and include the source URL.\n2. Ask for a KRPUS to NLRTM carrier schedule and include the source URL.\n```\n\n## 한국어\n\n### 개요\n\n`vessel-traffic-mcp`는 MCP 클라이언트가 허가된 해운/선박 데이터\n소스를 읽기 전용 도구로 조회할 수 있게 해주는 서버입니다.\n\n선박명, MMSI, IMO, 호출부호 기반 검색, 최신 위치 조회, 영역 조회,\n항만 호출, 선사 스케줄, 선박별 스케줄, 스케줄 지연 판단을 제공합니다.\n\n실시간 또는 공개 provider 응답은 반드시 `source.provider`와\n`source.landingUrl`을 포함해야 합니다. 이 프로젝트의 목적은 원\n서비스 유입과 출처 노출을 제공하는 것이며, 출처를 숨기거나\n재브랜딩하는 것이 아닙니다.\n\n공유를 도와줄 사람에게 보낼 짧은 문구와 커뮤니티용 글 초안은\n[`docs/marketing/help-us-spread.md`](./docs/marketing/help-us-spread.md)에\n정리되어 있습니다.\n\n### 빠른 시작\n\n```bash\ngit clone https://github.com/tools-mcp/vessel-traffic-mcp.git\ncd vessel-traffic-mcp\nnpm install\nnpm run lint\nnpm test\nnpm run build\n```\n\n기본 검증은 sanitize된 fixture만 사용합니다. 유료 provider나 live\nprovider를 호출하지 않으며 API 키, 계정, 네트워크 접근이 필요하지\n않습니다.\n\n### 로컬 MCP 설정\n\n로컬 데스크톱/CLI 클라이언트에서는 stdio transport를 사용합니다.\n\n```bash\nVESSEL_MCP_TRANSPORT=stdio npm start\n```\n\nCodex CLI, Claude Desktop, Claude Code 설정은\n[공통 MCP 설정 예시](#shared-mcp-config-snippets)를 사용하면 됩니다.\n전체 클라이언트 설정은 [`docs/runbooks/clients.md`](./docs/runbooks/clients.md),\nCodex 전용 설정은 [`docs/runbooks/codex.md`](./docs/runbooks/codex.md)에\n정리되어 있습니다.\n\n### 원격 MCP 설정\n\n원격 MCP 클라이언트는 Streamable HTTP `/mcp` 엔드포인트를 사용합니다.\n`/health`는 공개 health check입니다.\n\n```bash\nexport VESSEL_MCP_TRANSPORT=http\nexport VESSEL_MCP_HTTP_HOST=127.0.0.1\nexport VESSEL_MCP_HTTP_PORT=8765\nexport VESSEL_MCP_AUTH_TOKEN=\"\"\nnpm run start:http\n```\n\n`VESSEL_MCP_AUTH_TOKEN`을 설정한 경우 MCP 요청에는\n`Authorization: Bearer `이 필요합니다. 배포 문서는\n[`docs/runbooks/deployment-https.md`](./docs/runbooks/deployment-https.md)를\n참고하세요.\n\n### 공개 Provider\n\n브라우저 캡처 기반 공개 adapter는 명시적으로 켜야 합니다.\n\n```bash\nVESSEL_MCP_ENABLE_PUBLIC_PROVIDERS=myshiptracking,tradlinx,aisfriends npm start\n```\n\n- `myshiptracking`: 선박 자동완성, 선택 MMSI 기반 최신 위치, 지도 영역 조회.\n- `tradlinx`: FCL/LCL 선사 스케줄 조회.\n- `aisfriends`: 공개 지도 bounding-box 기반 영역 위치 조회. 선박명 검색은 지원하지 않습니다.\n- `shipfinder`: 명시적 provider 라우팅용 선박 자동완성 및 상세 API 형태.\n\n응답에는 항상 원 출처 provider와 사용자가 열 수 있는 출처 URL을\n포함합니다.\n\n### BYOK Provider\n\n유료/credential 기반 provider는 BYOK 방식으로만 사용합니다. 실제 키는\n로그, 에러, MCP 응답에 노출되지 않습니다.\n\n```bash\nexport VESSEL_MCP_PROFILE_MARINETRAFFIC__API_KEY=\"\"\nexport VESSEL_MCP_ENABLE_BYOK_PROVIDERS=\"marinetraffic,vesselfinder,aisstream,aishub,barentswatch,searates-schedules,routescanner-connect,vesselapi,datadocked,datalastic,globalfishingwatch\"\n```\n\n현재 credential 기반으로 런타임 등록 가능한 provider는 `marinetraffic`,\n`vesselfinder`, `aisstream`, `aishub`, `barentswatch`,\n`searates-schedules`, `routescanner-connect`, `vesselapi`, `datadocked`, `datalastic`, `globalfishingwatch`입니다. 기본 credential profile이\n설정된 provider는 자동으로 등록됩니다.\n\n자세한 내용은 [`docs/runbooks/credential-profiles.md`](./docs/runbooks/credential-profiles.md)와\n[`docs/runbooks/operator.md`](./docs/runbooks/operator.md)를 참고하세요.\n\n`provider_onboarding` MCP 도구를 사용하면 provider별 가입 URL, 필요한\nenv var, 현재 credential 설정 여부, 검증 단계를 확인할 수 있습니다.\n이 도구는 읽기 전용이며 계정 생성, 약관 동의, CAPTCHA, 이메일 인증,\n결제 정보 설정, API 키 발급을 대신 수행하지 않습니다.\n\n### 책임 있는 사용 및 제3자 권리\n\n이 프로젝트는 공익적 상호운용성, 업무 자동화 실험, 출처가 표시되는\n해운/선박 데이터 접근을 돕기 위해 오픈소스로 공개되었습니다. 이\n프로젝트는 제3자 서비스, 데이터베이스, 지도, 상표, 저작물, API 응답,\nprovider 콘텐츠를 복제, 재배포, 재브랜딩, 우회, 오용할 권리를 부여하지\n않습니다.\n\n소프트웨어를 어떻게 설정하고 사용하는지는 사용자 책임입니다. 사용자는\n관련 법령, provider 약관, 계정 권한, rate limit, 데이터 라이선스, 내부\n회사 정책을 직접 확인하고 준수해야 합니다. 인증, 유료 기능, CAPTCHA,\n접근 제어, robots 정책, 상업적 제한을 우회하기 위해 이 프로젝트를\n사용해서는 안 됩니다.\n\n작성자와 기여자는 참조된 모든 서비스와 데이터 provider의 권리와 약관을\n존중합니다. live/public provider 응답은 `source.provider`와\n`source.landingUrl`로 원 출처를 표시하고, 사용자가 원 서비스를 확인할 수\n있도록 설계되었습니다. 권리자, 서비스 운영자, 또는 관련 당사자가 근거\n있는 문제를 제기하면 maintainer는 신속히 검토하고, 필요한 경우 해당\nadapter, 문서, fixture, reference를 수정, 비활성화, 또는 제거하겠습니다.\n\n이 소프트웨어는 MIT 라이선스에 따라 보증 없이 제공됩니다. 이 README의\n문구는 법률 자문이 아니며, 각 사용 사례에 적용되는 약관과 법적 의무를\n검토하는 일을 대체하지 않습니다.\n\n### 에이전트 설정 프롬프트\n\n다른 코딩 에이전트에게 이 MCP를 설치하게 할 때 사용할 프롬프트입니다.\n\n```text\nhttps://github.com/tools-mcp/vessel-traffic-mcp 를 이 머신의 로컬\nstdio MCP 서버로 설치하고 설정해줘.\n\n먼저 README.md와 llms.txt를 읽어라. repo를 clone하고 `npm ci`,\n`npm run build`를 실행한 뒤, 로컬 MCP 클라이언트 설정에\n`dist/index.js`의 절대경로를 등록해라.\n\n`VESSEL_MCP_TRANSPORT=stdio`를 사용하고,\n`VESSEL_MCP_ENABLE_PUBLIC_PROVIDERS=myshiptracking,tradlinx,aisfriends`를 설정해라.\n\n로컬 MCP 클라이언트 설정 파일, env 파일, API 키, 쿠키, HAR 파일,\n브라우저 세션, raw capture는 커밋하지 마라. 다른 머신의 credential을\n복사하지 마라.\n\nMCP 클라이언트를 재시작한 뒤 다음으로 검증해라:\n1. EVER GIVEN 현재 위치를 조회하고 출처 URL을 함께 보여줘.\n2. KRPUS에서 NLRTM까지의 선사 스케줄을 조회하고 출처 URL을 함께 보여줘.\n```\n\n## 日本語\n\n### 概要\n\n`vessel-traffic-mcp` は、MCP クライアントから許可された海事データ\nソースを読み取り専用で参照するためのサーバーです。\n\n船名、MMSI、IMO、コールサインによる検索、最新位置、エリア検索、\n寄港情報、船会社スケジュール、船舶別スケジュール、遅延判定を\n提供します。\n\nライブまたは公開 provider の応答では、`source.provider` と\n`source.landingUrl` を必ず含めます。このプロジェクトは元サービスへ\nユーザーを誘導し、出典を明示することを目的としています。\n\n### クイックスタート\n\n```bash\ngit clone https://github.com/tools-mcp/vessel-traffic-mcp.git\ncd vessel-traffic-mcp\nnpm install\nnpm run lint\nnpm test\nnpm run build\n```\n\n標準の検証は sanitize 済み fixture のみを使います。有料 provider や\nlive provider は呼び出さず、API キー、アカウント、ネットワーク接続も\n不要です。\n\n### ローカル MCP 設定\n\nローカルのデスクトップ/CLI クライアントでは stdio transport を使います。\n\n```bash\nVESSEL_MCP_TRANSPORT=stdio npm start\n```\n\nCodex CLI、Claude Desktop、Claude Code の設定には\n[共通 MCP 設定例](#shared-mcp-config-snippets)を使用してください。\n\n### リモート MCP 設定\n\nリモート MCP クライアントでは Streamable HTTP の `/mcp` を使います。\n`/health` は公開 health check です。\n\n```bash\nexport VESSEL_MCP_TRANSPORT=http\nexport VESSEL_MCP_HTTP_HOST=127.0.0.1\nexport VESSEL_MCP_HTTP_PORT=8765\nexport VESSEL_MCP_AUTH_TOKEN=\"\"\nnpm run start:http\n```\n\n`VESSEL_MCP_AUTH_TOKEN` を設定した場合、MCP リクエストには\n`Authorization: Bearer ` が必要です。\n\n### 公開 Provider\n\nブラウザキャプチャ由来の公開 adapter は明示的に有効化します。\n\n```bash\nVESSEL_MCP_ENABLE_PUBLIC_PROVIDERS=myshiptracking,tradlinx,aisfriends npm start\n```\n\n- `myshiptracking`: 船舶オートコンプリート、選択 MMSI からの最新位置、\n 地図範囲検索。\n- `tradlinx`: FCL/LCL の船会社スケジュール検索。\n- `aisfriends`: 公開地図の bounding-box ベースのエリア位置検索。船名検索は未対応。\n- `shipfinder`: 明示的 provider ルーティング用の船舶検索と詳細 API 形状。\n\n### BYOK Provider\n\n有料または credential が必要な provider は BYOK のみです。実際のキーは\nログ、エラー、MCP 応答に出しません。\n\n```bash\nexport VESSEL_MCP_PROFILE_MARINETRAFFIC__API_KEY=\"\"\nexport VESSEL_MCP_ENABLE_BYOK_PROVIDERS=\"marinetraffic,vesselfinder,aisstream,aishub,barentswatch,searates-schedules,routescanner-connect,vesselapi,datadocked,datalastic,globalfishingwatch\"\n```\n\n現在 runtime で有効化できる credentialed provider は `marinetraffic`,\n`vesselfinder`, `aisstream`, `aishub`, `barentswatch`,\n`searates-schedules`, `routescanner-connect`, `vesselapi`, `datadocked`, `datalastic`, `globalfishingwatch` です。\n\n### エージェント設定プロンプト\n\n別のコーディングエージェントに MCP を設定させる場合のプロンプトです。\n\n```text\nhttps://github.com/tools-mcp/vessel-traffic-mcp を、このマシンの\nローカル stdio MCP サーバーとしてインストールして設定してください。\n\n最初に README.md と llms.txt を読んでください。repo を clone し、\n`npm ci` と `npm run build` を実行し、`dist/index.js` の絶対パスを\nローカル MCP クライアントに登録してください。\n\n`VESSEL_MCP_TRANSPORT=stdio` を使い、\n`VESSEL_MCP_ENABLE_PUBLIC_PROVIDERS=myshiptracking,tradlinx,aisfriends` を設定してください。\n\nローカル MCP クライアント設定、env ファイル、API キー、Cookie、HAR、\nブラウザセッション、raw capture を commit しないでください。他の\nマシンから credential をコピーしないでください。\n\n再起動後、EVER GIVEN の現在位置と出典 URL、KRPUS から NLRTM への\n船会社スケジュールと出典 URL を確認してください。\n```\n\n## 中文\n\n### 概览\n\n`vessel-traffic-mcp` 是一个只读 MCP 服务器，让 MCP 客户端能够通过\n统一工具接口访问已授权的海事数据来源。\n\n它支持按船名、MMSI、IMO、呼号搜索船舶，查询最新位置、区域位置、\n港口靠泊、承运人航线计划、船舶计划和延误判断。\n\n所有实时或公开 provider 的响应都必须包含 `source.provider` 和\n`source.landingUrl`。本项目用于向原始服务导流并明确显示出处，而不是\n隐藏或重新包装数据来源。\n\n### 快速开始\n\n```bash\ngit clone https://github.com/tools-mcp/vessel-traffic-mcp.git\ncd vessel-traffic-mcp\nnpm install\nnpm run lint\nnpm test\nnpm run build\n```\n\n默认验证只使用已清洗的 fixture，不调用付费或实时 provider，也不需要\nAPI key、账号或网络访问。\n\n### 本地 MCP 设置\n\n本地桌面和 CLI 客户端使用 stdio transport。\n\n```bash\nVESSEL_MCP_TRANSPORT=stdio npm start\n```\n\nCodex CLI、Claude Desktop、Claude Code 可使用\n[共享 MCP 配置片段](#shared-mcp-config-snippets)。\n\n### 远程 MCP 设置\n\n远程 MCP 客户端使用 Streamable HTTP `/mcp`，`/health` 是公开健康检查。\n\n```bash\nexport VESSEL_MCP_TRANSPORT=http\nexport VESSEL_MCP_HTTP_HOST=127.0.0.1\nexport VESSEL_MCP_HTTP_PORT=8765\nexport VESSEL_MCP_AUTH_TOKEN=\"\"\nnpm run start:http\n```\n\n设置 `VESSEL_MCP_AUTH_TOKEN` 后，MCP 请求需要\n`Authorization: Bearer `。\n\n### 公开 Provider\n\n浏览器捕获得到的公开 adapter 需要显式启用。\n\n```bash\nVESSEL_MCP_ENABLE_PUBLIC_PROVIDERS=myshiptracking,tradlinx,aisfriends npm start\n```\n\n- `myshiptracking`: 船舶自动完成、按选定 MMSI 查询最新位置、地图范围查询。\n- `tradlinx`: FCL/LCL 承运人航线计划查询。\n- `aisfriends`: 基于公开地图 bounding-box 的区域位置查询；不支持船名搜索。\n- `shipfinder`: 用于显式 provider 路由的船舶搜索和详情 API 形状。\n\n### BYOK Provider\n\n付费或需要 credential 的 provider 只能使用 BYOK。真实 key 不会出现在日志、\n错误或 MCP 响应中。\n\n```bash\nexport VESSEL_MCP_PROFILE_MARINETRAFFIC__API_KEY=\"\"\nexport VESSEL_MCP_ENABLE_BYOK_PROVIDERS=\"marinetraffic,vesselfinder,aisstream,aishub,barentswatch,searates-schedules,routescanner-connect,vesselapi,datadocked,datalastic,globalfishingwatch\"\n```\n\n当前可在 runtime 启用的 credentialed provider 是 `marinetraffic`,\n`vesselfinder`, `aisstream`, `aishub`, `barentswatch`,\n`searates-schedules`, `routescanner-connect`, `vesselapi`, `datadocked`, `datalastic`, `globalfishingwatch`。\n\n### Agent 设置提示词\n\n让其他编码 agent 安装此 MCP 时可使用以下提示词。\n\n```text\n请将 https://github.com/tools-mcp/vessel-traffic-mcp 安装并配置为本机\n本地 stdio MCP 服务器。\n\n先阅读 README.md 和 llms.txt。clone 仓库，运行 `npm ci` 和\n`npm run build`，然后在本地 MCP 客户端中用 `dist/index.js` 的绝对路径\n注册服务器。\n\n使用 `VESSEL_MCP_TRANSPORT=stdio`，并设置\n`VESSEL_MCP_ENABLE_PUBLIC_PROVIDERS=myshiptracking,tradlinx,aisfriends`。\n\n不要提交本地 MCP 客户端配置、env 文件、API key、cookie、HAR 文件、\n浏览器 session 或 raw capture。不要从其他机器复制 credentials。\n\n重启 MCP 客户端后验证：\n1. 查询 EVER GIVEN 当前船位，并显示来源 URL。\n2. 查询 KRPUS 到 NLRTM 的承运人航线计划，并显示来源 URL。\n```\n\n## Shared Reference\n\n### Shared MCP Config Snippets\n\nCodex CLI `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.vessel-traffic-mcp]\ncommand = \"node\"\nargs = [\"/absolute/path/to/vessel-traffic-mcp/dist/index.js\"]\n\n[mcp_servers.vessel-traffic-mcp.env]\nVESSEL_MCP_TRANSPORT = \"stdio\"\nVESSEL_MCP_ENABLE_PUBLIC_PROVIDERS = \"myshiptracking,tradlinx,aisfriends\"\n```\n\nClaude Desktop / Claude Code config:\n\n```json\n{\n \"mcpServers\": {\n \"vessel-traffic-mcp\": {\n \"command\": \"node\",\n \"args\": [\"/absolute/path/to/vessel-traffic-mcp/dist/index.js\"],\n \"env\": {\n \"VESSEL_MCP_TRANSPORT\": \"stdio\",\n \"VESSEL_MCP_ENABLE_PUBLIC_PROVIDERS\": \"myshiptracking,tradlinx,aisfriends\"\n }\n }\n }\n}\n```\n\n### Provider Implementation Status\n\nThe PRD is intentionally broader than the adapters enabled by default.\nCurrent status:\n\n| Group | Runtime status | Providers |\n| --- | --- | --- |\n| Default | enabled with no env | `fixture` |\n| Public opt-in | `VESSEL_MCP_ENABLE_PUBLIC_PROVIDERS` | `aisfriends`, `myshiptracking`, `shipfinder`, `tradlinx-schedule` |\n| Credentialed implemented | `VESSEL_MCP_ENABLE_BYOK_PROVIDERS` or configured default profile | `marinetraffic`, `vesselfinder`, `aisstream`, `aishub`, `barentswatch`, `searates-schedules`, `routescanner-connect`, `vesselapi`, `datadocked`, `datalastic`, `globalfishingwatch` |\n| Planned schedule APIs | cataloged, not implemented | `linescape-schedule-api` |\n| Not started commercial AIS | cataloged, not implemented | `spire-maritime`, `orbcomm-commtrace` |\n| Discovery or enterprise review | cataloged only | `openais`, `noaa-marinecadastre`, `iqax-bigschedules`, `cargosmart-schedule`, `poseidon-ais`, `ais-now`, `fleetmon`, `windward`, `polestar-global`, `spglobal-seaweb`, `lloyds-list-intelligence` |\n\nThe structured source of truth is\n[`config/provider-catalog.example.json`](./config/provider-catalog.example.json)\nand the human-readable inventory is\n[`docs/provider-catalog.md`](./docs/provider-catalog.md).\n\n### Local Vessel Map UI\n\nFor a local visual check with ship-name input and a map:\n\n```bash\nnpm run start:map\n```\n\nOpen `http://127.0.0.1:8787` and search `EVER GIVEN` or MMSI\n`353136000`. The UI displays a map marker and a visible source link.\n\n### Schedule Tools\n\nRegistered read-only schedule tools:\n\n- `carrier_schedule_search`\n- `vessel_schedule`\n- `schedule_delay_predict`\n\nRegistered read-only provider/setup tools:\n\n- `provider_status`\n- `data_sources`\n- `credential_profiles`\n- `provider_onboarding`\n\nFixture-backed checks:\n\n```text\nKRPUS에서 NLRTM으로 가는 선사 스케줄을 조회하고, 출처 URL도 같이 보여줘.\nEVER GIVEN 선박 스케줄을 조회하고 ETA 지연 여부를 계산해줘.\n```\n\nSchedule-provider candidates are tracked in\n[`docs/provider-catalog.md`](./docs/provider-catalog.md). Tradelinx has\nan explicit opt-in `carrier_schedule_search` adapter backed by\nsanitized browser-captured endpoint shapes documented in\n[`docs/runbooks/schedule-api-capture-results.md`](./docs/runbooks/schedule-api-capture-results.md).\n\n### Capture And Safety Boundary\n\nThis project does not aim to bypass commercial services. It supports:\n\n- Official APIs and open-data feeds.\n- User-provided API credentials and organization-level BYOK credential\n profiles for paid providers.\n- Sanitized HAR/network samples from operator-owned, authorized\n browser sessions, only where allowed by service terms.\n\nIt must not store raw cookies, bearer tokens, API keys, private HAR\nfiles, raw captures, or private browser sessions in the repository.\nThe full hard-rule list lives in [`AGENTS.md`](./AGENTS.md), and\nsecurity expectations are in [`SECURITY.md`](./SECURITY.md).\n\nAuthorized capture tooling is documented in\n[`docs/runbooks/capture-execution.md`](./docs/runbooks/capture-execution.md).\nThe sanitized import command is `npm run capture:import`, and traffic\nIR generation is `npm run capture:ir`.\n\n> Not for navigation. AIS data returned by configured providers may be\n> delayed, incomplete, or inaccurate. This project is not a\n> safety-critical navigation tool.\n\n### Project Layout\n\n```text\nsrc/\n capture/ sanitized capture fixture importer + traffic IR CLI\n config/ credential profile loader, provider catalog\n providers/ adapter interfaces, registry, router, rate limit, TTL cache\n server/ MCP transports and tool handlers\n tools/ read-only tool definitions\n util/ structured logging and redaction helpers\ntest/ node:test deterministic tests; fixture-backed\ndocs/ PRD, TDD, provider catalog, and runbooks\n```\n\n### Documentation\n\n- [`llms.txt`](./llms.txt) — compact agent-facing project brief.\n- [`docs/index.html`](./docs/index.html) — static agent discovery page\n published through GitHub Pages.\n- [`server.json`](./server.json) — MCP Registry metadata for the\n `io.github.tools-mcp/vessel-traffic-mcp` namespace.\n- [`AGENTS.md`](./AGENTS.md) — project hard rules.\n- [`CODE_OF_CONDUCT.md`](./CODE_OF_CONDUCT.md) — collaboration\n expectations.\n- [`docs/PRD.md`](./docs/PRD.md) — product requirements.\n- [`docs/TDD.md`](./docs/TDD.md) — technical design.\n- [`docs/provider-catalog.md`](./docs/provider-catalog.md) — provider\n inventory and routing policy.\n- [`docs/runbooks/operator.md`](./docs/runbooks/operator.md) —\n end-to-end operator runbook.\n- [`docs/runbooks/clients.md`](./docs/runbooks/clients.md) — client\n setup for Claude Desktop, Claude Code, ChatGPT remote MCP, and MCP\n Inspector.\n- [`docs/runbooks/codex.md`](./docs/runbooks/codex.md) — Codex CLI MCP\n wiring and Codex plugin metadata state.\n- [`docs/runbooks/credential-profiles.md`](./docs/runbooks/credential-profiles.md)\n — BYOK profile handling.\n- [`docs/runbooks/deployment-https.md`](./docs/runbooks/deployment-https.md)\n — HTTPS deployment for the Streamable HTTP MCP endpoint.\n- [`docs/runbooks/release-checklist.md`](./docs/runbooks/release-checklist.md)\n — pre-release safety checklist.\n- [`docs/runbooks/public-sharing.md`](./docs/runbooks/public-sharing.md)\n — GitHub, MCP Registry, Smithery, Glama, PulseMCP, and launch-post\n sharing checklist.\n- [`docs/runbooks/api-capture-reference-only.md`](./docs/runbooks/api-capture-reference-only.md)\n — reference-only boundary for raw capture sessions.\n- [`docs/runbooks/browser-api-capture-results.md`](./docs/runbooks/browser-api-capture-results.md)\n — sanitized browser capture results for vessel APIs.\n- [`docs/runbooks/schedule-api-capture-results.md`](./docs/runbooks/schedule-api-capture-results.md)\n — sanitized browser capture results for schedule APIs.\n- [`docs/discoverability.md`](./docs/discoverability.md) — package,\n repository, and documentation discoverability contract.\n\n### Topics\n\n`vessel-traffic-mcp` is intended to be findable from MCP and plugin\nsearch surfaces. The same set is reflected in `package.json` keywords\nand suggested GitHub topics.\n\n- vessel AIS MCP\n- ship tracking MCP\n- MarineTraffic MCP\n- Claude MCP (Claude Desktop, Claude Code)\n- ChatGPT MCP (ChatGPT remote MCP connector)\n- Codex plugin (Codex / OpenAI plugin / marketplace workflows)\n- Gemini MCP (Gemini CLI and Gemini Code Assist)\n- MCP / Model Context Protocol server\n- AIS / vessel tracking / ship tracking\n- BYOK paid-provider routing (MarineTraffic, VesselFinder, AISStream,\n AISHub, BarentsWatch, SeaRates, Routescanner, VesselAPI, Data Docked,\n and other catalog entries)\n\n### Contributing\n\nContributions are welcome. Please read\n[`CONTRIBUTING.md`](./CONTRIBUTING.md) first. The project has\nnon-negotiable safety rules around credentials, capture fixtures, and\nthe read-only contract.\n\nUse GitHub Issues for bugs, provider requests, and authorized capture\nreviews. Use GitHub Discussions for roadmap, integration, and\ncollaboration threads. The sharing checklist is in\n[`docs/runbooks/public-sharing.md`](./docs/runbooks/public-sharing.md).\n\n### Security\n\nDo not file a public GitHub issue for a suspected vulnerability. See\n[`SECURITY.md`](./SECURITY.md) for the private reporting channel.\n\n### License\n\n[MIT](./LICENSE). See [NOTICE](./NOTICE) for the not-for-navigation notice.\n", "bytes": 30807, "sha": "ac8adff2a6298c6b35c2999f2337dbed2df3a101ec52a2a03f374c4bfeeedbd7", "repo_slug": "tools-mcp/vessel-traffic-mcp", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_tools_mcp_vessel_traffic_mcp_31cf611a/readme" }