Metadata-Version: 2.4
Name: mcp-shipxy-api
Version: 0.1.0
Summary: Shipxy MCP server and CLI for maritime vessel, port, route, weather, and tide APIs.
Author: garrettXu
License-Expression: MIT
Project-URL: Homepage, https://github.com/garrettXu/mcp-shipxy-api
Project-URL: Repository, https://github.com/garrettXu/mcp-shipxy-api
Project-URL: Issues, https://github.com/garrettXu/mcp-shipxy-api/issues
Keywords: shipxy,mcp,maritime,vessel,shipping,cli
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.28.1
Requires-Dist: mcp[cli]>=1.11.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: requests>=2.31.0

# shipxy-api-mcp

<!-- mcp-name: io.github.garrettxu/mcp-shipxy-api -->

**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](https://api.shipxy.com/v3/console/overview).  
**Note:** The API key is required for all requests.

### 2. Installation

Install from PyPI after release:

```bash
pipx install mcp-shipxy-api
```

Or install into an existing virtual environment:

```bash
pip install mcp-shipxy-api
```

For local source development:

```bash
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:

```json
{
  "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:

```bash
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:

```powershell
.\.venv\Scripts\Activate.ps1
```

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

```bash
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:

```bash
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:

```json
{
  "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:** 400-010-8558 / 010-8286 8599
