mcp-shipxy-api 0.1.0

Shipxy MCP server and CLI for maritime vessel, port, route, weather, and tide APIs.

shipxy-api-mcp

Shipxy MCP Server is a fully MCP-compliant, open-source Location-Based Service (LBS) solution for maritime scenarios, providing a comprehensive suite of ship and port APIs and tools for developers and AI agents. It enables seamless integration of real-time vessel data, route planning, weather, tides, and more into your applications.

🚀 Introduction

Shipxy MCP Server empowers your applications, LLMs, and agents with advanced maritime data and geospatial intelligence, including:

• Ship Information & Tracking: Real-time vessel position, static info, fleet, and area queries.
• Port & Berth Data: Global port search, berth/anchor/ETA queries, port call records.
• Route Planning: Point-to-point and port-to-port route planning.
• Weather & Tides: Marine weather, typhoon, and tide station data.
• Rich Maritime APIs: Ship registry, particulars, approach events, and more.

All APIs follow the MCP protocol and can be called from any MCP-compliant client, LLM, or agent platform.

🛠️ Key Features

• Full MCP Protocol Support: Seamless integration with any MCP-compliant agent, LLM, or platform.
• Comprehensive Maritime Data: Ships, ports, routes, weather, tides, and more.
• Real-Time & Historical Data: Live vessel tracking, voyage history, and event records.
• Open Source & Extensible: MIT licensed, easy to customize and extend.

⚡ Quick Start

1. Get Your API Key

Register and create a server-side API Key at Shipxy Open Platform.
Note: The API key is required for all requests.

2. Installation

Install from PyPI after release:

pipx install mcp-shipxy-api

Or install into an existing virtual environment:

pip install mcp-shipxy-api

For local source development:

pip install -r requirements.txt

3. Configuration

Create a .env file in your project root:

SHIPXY_API_KEY=your_api_key_here

4. Start the Server

Recommended: Use an mcp.json configuration file for easy integration with MCP CLI and agent platforms. Example:

{
  "mcpServers": {
    "shipxy-api-mcp": {
      "command": "python",
      "args": ["/path/to/your/server.py"],
      "env": {
        "SHIPXY_API_KEY": "your_api_key_here"
      }
    }
  }
}

CLI Usage

This project also provides a cross-platform CLI. Business commands stay flat and map directly to MCP tool names, with underscores converted to dashes:

python -m venv .venv
source .venv/bin/activate
pip install -e .

shipxy auth status
shipxy tools
shipxy schema search-ship
shipxy search-ship COSCO --max 5
shipxy get-single-ship 413211000
shipxy search-port Shanghai
shipxy plan-route-by-port CNSHA SGSIN
shipxy get-weather-by-point --lng 123.58414 --lat 27.37979

Windows PowerShell activation:

.\.venv\Scripts\Activate.ps1

The CLI defaults to JSON output for LLM and agent calls. For human-readable output:

shipxy search-ship COSCO --max 5 --format table
shipxy search-ship COSCO --max 5 --format pretty
shipxy search-ship COSCO --max 5 --format ndjson

You can also start the MCP server through the CLI:

shipxy mcp start
shipxy mcp start --transport sse --host 127.0.0.1 --port 8000

Agent and MCP clients should configure the API key through the SHIPXY_API_KEY environment variable:

{
  "mcpServers": {
    "shipxy": {
      "command": "shipxy",
      "args": ["mcp", "start"],
      "env": {
        "SHIPXY_API_KEY": "your_api_key_here"
      }
    }
  }
}

🧩 Supported APIs

Tool Name	Description
search_ship	Fuzzy search for ships by MMSI, IMO, name, or call sign
get_single_ship	Query real-time info for a single ship by MMSI
get_many_ship	Query real-time info for multiple ships by MMSI list
get_fleet_ship	Query all ships in a fleet
get_surrounding_ship	Query ships within 10nm of a given ship
get_area_ship	Query ships in a specified area
get_ship_registry	Query ship registry/country info
search_ship_particular	Query ship particulars by MMSI/IMO/call sign/name
search_port	Fuzzy search for ports by name or code
get_berth_ships	Query ships currently berthed at a port
get_anchor_ships	Query ships at anchor at a port
get_eta_ships	Query ships with ETA to a port
get_ship_track	Query historical track points for a ship
search_ship_approach	Query ship-to-ship approach events
get_port_of_call_by_ship	Query port call records for a ship
get_port_of_call_by_port	Query port call records for a port
plan_route_by_point	Plan route between two coordinates
plan_route_by_port	Plan route between two ports
get_single_eta_precise	Get ETA and voyage info for a ship
get_weather_by_point	Query marine weather by coordinates
get_weather	Query marine weather by area
get_all_typhoon	List recent typhoons
get_single_typhoon	Query details for a specific typhoon
get_tides	List tide stations
get_tide_data	Query tide data for a station

🌍 Application Scenarios

• Maritime Logistics & Fleet Management
• Vessel Tracking & Monitoring
• Port Operations & ETA Prediction
• Smart Shipping & Route Optimization
• Marine Weather & Safety Applications

📦 Project Structure

.
├── server.py           # MCP server entry point
├── ship_service.py     # Shipxy API integration and business logic
├── requirements.txt    # Python dependencies
├── pyproject.toml      # Project metadata
└── README.md           # This file

📄 License

MIT © shipxy-api-mcp contributors

📞 Contact

For more information or business inquiries, please contact:

Phone: [phone]