APM Terminal

You run an MCP server that exposes vessel, crane, and productivity data from APM Terminal as programmable tools. This enables natural-language style queries and automated integrations to query live operations data via a local server or remote endpoint.

How to use

You interact with the MCP server using a client that understands MCP protocols. Start the server locally or run it on a host, then connect your client by using the server’s connection details. You can call programmatic tools to retrieve vessel visits, inbound vessels, vessel details, today’s visits, vessel productivity (CMPH), crane assignments, longest-working crane, date-range vessel queries, and crane delays. Use these tools to build dashboards, automate reports, or power chat-based queries that return structured data.

How to install

Prerequisites: you need Node.js installed (and npm) to build and run the MCP server. You also prepare a MySQL database with the expected schema and credentials.

Step 1. Install dependencies

npm install

Step 2. Create a configuration file based on the example and edit credentials

DB_HOST=localhost
DB_PORT=3306
DB_USER=your_database_user
DB_PASSWORD=your_database_password
DB_NAME=apm_terminal
DB_CONNECTION_LIMIT=10
OPENAI_API_KEY=YOUR_OPENAI_API_KEY

Step 3. Build the TypeScript code

npm run build

Step 4. Run in production mode

npm start

Step 5. Run with local development tooling or set up an MCP client to connect to the local server as described in configuration steps below.

Configuration and runtime details

You can run the MCP server as a local stdio process or connect to it via an MCP JSON configuration. The following example shows how you would configure a local stdio server to execute the MCP entry point. This is useful when running on your workstation or a local development environment.

{
  "mcpServers": {
    "apm-terminal": {
      "type": "stdio",
      "command": "node",
      "args": ["/Applications/MAMP/htdocs/MCP/build/index.js"],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "3306",
        "DB_USER": "your_database_user",
        "DB_PASSWORD": "your_database_password",
        "DB_NAME": "apm_terminal"
      }
    }
  }
}

Tools and usage notes

The MCP server provides a set of programmatic tools to access terminal data. Each tool returns relevant fields described in the following list.

• get_vessel_visits: Retrieve up-to-date vessel visits with status, planned moves, and executed moves.

Available tools

get_vessel_visits

Returns up to 100 most recent vessel visits with vessel name, visit ID, phase, arrival/departure times, week/month/year, total executed moves, and total planned moves.

get_inbound_vessels_current_year

Returns inbound vessels for the current year with visit ID, vessel name, phase, service/line, ETA/ETD, port hours, and estimated moves.

get_vessel_details

Returns detailed vessel information for a given visitId, including service, phase, key timestamps, port hours, estimated moves, and idle times.

get_visits_today

Returns all visits scheduled for today with vessel name, visit ID, phase, and ETA/ETD times.

get_vessel_productivity

Returns CMPH metrics for a vessel, including total moves, working hours, and CMPH.

get_vessel_cranes

Returns crane assignments with first/last move times for a vessel.

get_vessel_longest_crane

Identifies the longest-working crane for active vessels.

get_inbound_vessels_date_range

Queries inbound vessels within a specified date range.

get_crane_delays

Retrieves historical crane delay information.