# 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)