◆ NTHMAP
Sign in Sign up free
Docs

MCP server

Give Claude, ChatGPT, or any MCP-capable AI agent direct access to live vessels, infrastructure, events, and the draw tool.

The NTHMAP MCP server exposes every NTHMAP dataset as a set of tools that an MCP-capable AI agent can call directly. It speaks the Model Context Protocol over stdio, so any agent that supports MCP — Claude Desktop, Claude Code, Cursor, a custom Anthropic SDK agent — can use it with zero code.

What this unlocks

With NTHMAP MCP installed, your AI agent can:

  • Answer questions like "How many crude tankers are near the Strait of Hormuz right now?" with real data, not guesses
  • Draw a region on its own, analyze the cargo flows inside, and write a trading briefing
  • Monitor for events in a bbox and alert you when something changes
  • Cross-reference vessels, infrastructure, and price data in a single reasoning chain

The agent doesn't need to know anything about the NTHMAP API. The MCP tools are self-describing — the agent just sees search_vessels, get_vessel, list_events, etc., each with typed parameters and a natural-language description.

Install

Prerequisites

  • Python 3.9+
  • A NTHMAP Pro account (MCP is a Pro feature)
  • An API key (create one)

Install the MCP package

pip install nthmap-mcp

Or install from source:

git clone https://github.com/nthmap/nthmap-mcp
cd nthmap-mcp
pip install -e .

Configure your agent

Claude Desktop / Claude Code

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "nthmap": {
      "command": "python",
      "args": ["-m", "nthmap_mcp"],
      "env": {
        "NTHMAP_API_KEY": "ntm_live_...",
        "NTHMAP_BASE_URL": "https://nthmap.com"
      }
    }
  }
}

Restart Claude. You should see a 🔧 nthmap chip appear in the chat input. That's it — the agent can now call NTHMAP tools.

Cursor

Add to ~/.cursor/mcp.json with the same shape.

Custom Anthropic SDK agent

from anthropic import Anthropic
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

server = StdioServerParameters(
    command="python",
    args=["-m", "nthmap_mcp"],
    env={"NTHMAP_API_KEY": "ntm_live_..."}
)
async with stdio_client(server) as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()
        tools = await session.list_tools()
        # ...pass `tools` into your Anthropic API call

Tools exposed

The MCP server exposes these tools to the agent:

search_vessels

Find vessels matching natural filters. Accepts a bounding box, vessel types, speed range, load range, and a result limit.

Agent: "Find me all crude tankers over 85% loaded near Hormuz"
Tool call: search_vessels(bbox=[54,25,58,28], types=["Crude Tanker"], min_load=85)
Returns:  array of matching vessels

get_vessel

Retrieve full detail for a specific vessel by MMSI.

get_vessel_track

Last 24 hours of positions for a vessel — useful for the agent to reason about where the ship has been.

list_infrastructure

List infrastructure assets — refineries, LNG terminals, pipelines, ports, mines — filtered by type, commodity, or bbox.

list_events

Active world events in a region. The agent can filter by event type (hurricane, earthquake, wildfire, conflict, sanctions) and severity.

get_chokepoints

Live status of the 8 strategic maritime chokepoints, including vessel counts and average speed.

get_prices

Current prices for all 12 commodities, or historical series for a specific symbol.

analyze_region

The most powerful tool. Give it any GeoJSON polygon or a bbox, it runs the draw analysis on the NTHMAP backend and returns a full regional snapshot:

  • Total vessels inside + commodity breakdown
  • Estimated total cargo in MT
  • Infrastructure assets inside
  • Active events inside
  • Optional AI flow narrative

This is the single tool call that turns "look at this area on a map" into a structured answer an agent can reason over.

flow_analysis

Higher-level regional flow narrative — "how much crude is headed to Europe right now?"

vessel_context

Generate a three-sentence trading context summary for a specific vessel, including cargo significance, route implications, and price impact.

nl_query

Let the agent do natural-language → filter parameter conversion inside the NTHMAP backend rather than trying to parse filters itself. Pass a plain-English question and get back a structured filter object.

Example conversation

You: What's the biggest risk to European crude supply right now?

Claude (using NTHMAP MCP):

Thinking… I should check the chokepoints, active events, and inbound flows.

[calls get_chokepoints] [calls list_events(types=["conflict","hurricane"], bbox=[-20,10,65,70])] [calls flow_analysis(region="Europe", commodity="Crude Oil")]

Three things are notable right now:

  1. Gulf of Aden chokepoint is flagged Alert — vessels are transiting at 15.2 knots (vs 13 normal), indicating avoidance behavior around Houthi threat zones.
  2. There's an active conflict event in the Red Sea southern approach with a 200km radius.
  3. Europe has 37 crude tankers inbound carrying an estimated 8.7 million MT, with average ETA 9.2 days. That's roughly 60 million barrels.

The combination means Europe's next two weeks of crude supply is concentrated in ships that may need to reroute around the Cape of Good Hope (adding ~14 days), so any disruption now wouldn't be felt in Rotterdam until late this month.

Permissions

All MCP tools use the scopes on your API key. A read-only key can query data but cannot save views, drawings, or prompts. Create a separate write-scoped key if your agent needs to persist state back to NTHMAP.

Rate limits

MCP tools count against your API key rate limits. On Pro that's 300 requests/minute, which is plenty for typical agent workflows — the draw-analyze call alone can replace 10+ individual queries.

Troubleshooting

Agent doesn't see the nthmap tools

  • Check the MCP client logs (Claude Desktop: Help → Developer Tools → Console)
  • Verify python -m nthmap_mcp --version works from a terminal
  • Make sure the path to Python in your config is the same one where you installed nthmap-mcp

"401 Unauthorized" in tool responses

Your NTHMAP_API_KEY env var is missing or invalid. Create a new key and update the config.

"402 Pro tier required"

Your account isn't Pro. Upgrade at /app.

Source

The MCP server is a single Python module. View or fork it on the NTHMAP GitHub.