# Maersk Vessel Deadlines MCP Server
This project is a **Model Context Protocol (MCP) server** that provides programmatic access to Maersk vessel information, including vessel schedules and shipment deadlines. It exposes tools that can be used by MCP-compatible clients (like Claude Desktop, GPTs, or other AI assistants) to retrieve up-to-date shipping data from Maersk's public APIs.
## About Model Context Protocol (MCP)
The [Model Context Protocol](https://modelcontextprotocol.io) is an open standard that enables AI assistants to connect to external data sources and tools. MCP servers provide a standardized way for AI models to access real-time information and perform actions through a secure, structured interface.
## Features & Available Tools
The MCP server exposes the following tools:
### 1. `get_vessel_imo`
- **Description:** Retrieve the IMO (International Maritime Organization) number for a vessel by its name.
- **Input:** Vessel name (string)
- **Output:** IMO number (string)
### 2. `get_vessel_schedule`
- **Description:** Retrieve the schedule and shipment deadlines for a vessel, given its IMO number, voyage number, port of loading, and ISO country code.
- **Inputs:**
- `vessel_imo`: IMO number of the vessel (string)
- `voyage_number`: Voyage number (string)
- `port_of_loading`: Port of loading (string)
- `iso_country_code`: ISO country code of the port (string)
- **Output:** Human-readable summary of the vessel's schedule and deadlines
### 3. `get_port_calls`
- **Description:** Retrieve the vessels calling on a specific port, given its Country and Port of Loading city for the next one week.
- **Inputs:**
- `country_code`: ISO Country Code
- `city_name`: POL City name
- **Output:** Human-readable summary of vessels calling upon the port in the next 1 week.
These tools are defined in `main.py` and are accessible via the MCP protocol for integration with AI assistants and other MCP clients.
## Requirements
- Python 3.11+
- Maersk API Consumer Key (set as `CONSUMER_KEY` in your environment)
## Installation & Usage
### Using Docker (Recommended)
A prebuilt Docker image is available at [`dipankan001/maersk-mcp:v1`](https://hub.docker.com/r/dipankan001/maersk-mcp):
```bash
docker pull dipankan001/maersk-mcp:v1
docker run -e CONSUMER_KEY=INSERT_API_KEY_HERE dipankan001/maersk-mcp:v1
```
### Connecting to MCP Clients
#### Claude Desktop
Add this to your Claude Desktop configuration:
```json
{
"mcpServers": {
"maersk-mcp-server": {
"command": "docker",
"args": ["run", "--rm", "-i", "-e", "CONSUMER_KEY=<INSERT_API_KEY_HERE>", "dipankan001/maersk-mcp:v1"]
}
}
}
```
#### Other MCP Clients
For other MCP-compatible clients, configure the server using the appropriate connection method (HTTP, stdio, etc.) as specified in the [MCP specification](https://github.com/modelcontextprotocol/specification).
## Endpoints
The app exposes MCP tools for:
- Getting vessel IMO numbers
- Fetching vessel schedules and shipment deadlines
- Fetching active port call vessels
See `main.py` for details on available tools and their parameters.
## Resources
- [Model Context Protocol Documentation](https://modelcontextprotocol.io)
- [MCP Specification](https://github.com/modelcontextprotocol/specification)
- [MCP GitHub Repository](https://github.com/modelcontextprotocol/modelcontextprotocol)
