Datalastic MCP Server

MCP (Model Context Protocol) server for the Datalastic Marine AIS Data API. This server enables AI assistants like Claude to access real-time vessel tracking, port information, and maritime data through the Datalastic API.

📖 Documentation:

• New Users: Start with QUICK_START.md (5 minutes)

• Complete Guide: See USER_GUIDE.md (comprehensive)

Features

Core Functionality

• Vessel Tracking: Get real-time location, speed, course, and destination of vessels

• Vessel History: Access historical position data for vessels (since Aug 2021)

• Vessel Information: Access detailed vessel specifications and technical data

• Area Search: Find all vessels within a geographic radius

• Port Search: Look up ports by name, type, location, or country

• Fleet Tracking: Monitor multiple vessels simultaneously (up to 100)

Advanced Features

• MCP Resources: Subscribe to real-time vessel data using custom URI schemes

• Smart Caching: Automatic response caching with configurable TTLs (reduces API calls by ~70%)

• Rate Limit Tracking: Monitor your API usage with built-in request counting

• Server Statistics: View cache hit rates and API usage metrics

• Comprehensive Testing: Full test suite with 24+ tests (100% passing)

Related MCP server: VesselAPI MCP Server

Installation

Prerequisites

• Python 3.10 or higher

• A Datalastic API key (get one at https://datalastic.com/)

Setup

1. Install dependencies:

pip install mcp httpx pydantic

Or if using the repository:

cd /path/to/datalastic-mcp
pip install -e .

2. Set up your API key in one of two ways:

Option A: Environment Variable

export DATALASTIC_API_KEY="your-api-key-here"

Option B: File (recommended for development) Create a file named datalastic_api_key.txt in the project root containing your API key.

Usage

With Claude Desktop

Add this configuration to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "datalastic": {
      "command": "python",
      "args": ["-m", "datalastic_mcp"],
      "cwd": "/Users/rob/projects/Datalastic/MCP",
      "env": {
        "DATALASTIC_API_KEY": "your-api-key-here"
      }
    }
  }
}

Note: Replace /Users/rob/projects/Datalastic/MCP with the actual path to this project.

With MCP Inspector (for testing)

Test the server interactively:

npx @modelcontextprotocol/inspector python -m datalastic_mcp

Direct Usage

Run the server directly:

python -m datalastic_mcp

Available Tools

1. get_vessel_location

Get real-time location and status of a specific vessel.

Parameters:

• identifier_type: Type of identifier - uuid, mmsi, or imo

• identifier_value: The identifier value (e.g., MMSI "566093000")

• detailed: (optional) Set to true for enhanced data including ETA, ATD, draft

Example queries:

• "Where is vessel with MMSI 566093000?"

• "Get detailed location info for ship with IMO 9525338"

• "Show me the current position of MAERSK CHENNAI"

2. get_vessel_info

Get detailed specifications and static information about a vessel.

Parameters:

• identifier_type: Type of identifier - uuid, mmsi, or imo

• identifier_value: The identifier value

Example queries:

• "What are the specifications of vessel with IMO 9525338?"

• "Show me details about the ship with MMSI 566093000"

• "Get tonnage and dimensions for this vessel"

3. find_vessels_in_area

Find all vessels within a radius of geographic coordinates.

Parameters:

• latitude: Center point latitude (e.g., 51.9225)

• longitude: Center point longitude (e.g., 4.4792)

• radius_nautical_miles: Search radius in nautical miles (max 50)

Example queries:

• "Show me all vessels within 25 nautical miles of Rotterdam port (51.9225, 4.4792)"

• "Find ships near coordinates 40.7128, -74.0060 within 10 nautical miles"

• "What vessels are in the area around Singapore?"

4. search_ports

Search for ports by various criteria.

Parameters:

• name: (optional) Port name to search for

• fuzzy: (optional) Enable fuzzy name matching (default: false)

• port_type: (optional) Filter by port type

• country_iso: (optional) Two-letter country code (e.g., "NL")

• latitude, longitude, radius_nautical_miles: (optional) Geographic search

Example queries:

• "Find all ports named Rotterdam"

• "Search for container ports in the Netherlands"

• "Show me ports near coordinates 1.2897, 103.8501"

• "Find anchorages in Singapore"

5. track_multiple_vessels

Get current status of multiple vessels at once (up to 100).

Parameters:

• vessels: Array of vessel identifiers, each with type and value

Example queries:

• "Track these vessels: MMSI 566093000, IMO 9525338, and MMSI 477123456"

• "Show me the status of my fleet of 10 vessels"

6. get_vessel_history

Get historical position data for a vessel over time.

Parameters:

• identifier_type: Type of identifier - uuid, mmsi, or imo

• identifier_value: The identifier value

• days: (optional) Number of days of history (e.g., 5 for last 5 days)

• from_date: (optional) Start date in YYYY-MM-DD format

• to_date: (optional) End date in YYYY-MM-DD format

Returns:

• Historical positions with timestamps, coordinates, speed, course, heading, destination

• Data available since August 10, 2021

Note: Use either days OR from_date/to_date, not both.

Example queries:

• "Show me the last 5 days of position history for vessel with MMSI 566093000"

• "Get vessel history for IMO 9525338 from 2025-10-01 to 2025-10-15"

• "What was the route of MAERSK CHENNAI over the past week?"

7. get_server_stats

Get server performance and usage statistics.

Parameters: None

Returns:

• Cache statistics (hits, misses, hit rate, entries)

• Rate limit information (requests this hour, time until reset)

Example queries:

• "Show me the server stats"

• "What's the cache hit rate?"

• "How many API requests have I made this hour?"

MCP Resources

The server exposes real-time data through custom URI schemes:

vessel:// URI

Access real-time vessel data:

• Format: vessel://<identifier_type>/<identifier_value>

• Examples:

  • vessel://mmsi/566093000

  • vessel://imo/9525338

  • vessel://uuid/b8625b67-7142-cfd1-7b85-595cebfe4191

area:// URI

Monitor vessels in a geographic area:

• Format: area://<latitude>/<longitude>/<radius>

• Example: area://51.9225/4.4792/10 (Rotterdam, 10 NM radius)

Note: Resources automatically use caching and return detailed vessel information.

API Endpoints Used

The server connects to the following Datalastic API endpoints:

• /vessel - Basic vessel tracking

• /vessel_pro - Enhanced vessel tracking

• /vessel_info - Vessel specifications

• /vessel_history - Historical position data

• /vessel_bulk - Multiple vessel tracking

• /vessel_inradius - Area-based vessel search

• /port_find - Port search

Performance & Caching

The server includes an intelligent caching layer that significantly reduces API calls:

Cache TTL (Time To Live)

• Vessel positions: 60 seconds (frequently changing data)

• Vessel specifications: 5 minutes (rarely changes)

• Vessel history: 10 minutes (historical data doesn't change)

• Port information: 1 hour (almost never changes)

• Area searches: 45 seconds

Cache Benefits

• Reduced API calls: ~70% reduction in repeated queries

• Faster responses: Cached data returns instantly

• Lower costs: Fewer API requests = lower subscription costs

• Better UX: Faster response times for users

Rate Limiting

The server tracks API usage automatically:

• Request counting per hour

• Automatic counter reset

• Usage statistics available via get_server_stats tool

Tip: Use get_server_stats to monitor your cache performance and API usage.

Error Handling

The server handles common errors gracefully:

• Authentication errors: Invalid or missing API key

• Rate limiting: API quota exceeded (tracked automatically)

• Not found: Vessel or port not found

• Network errors: Connection timeouts or failures

• Validation errors: Invalid parameters or values

Data Types

Vessel Identifiers

• UUID: Unique identifier assigned by Datalastic

• MMSI: Maritime Mobile Service Identity (9-digit number)

• IMO: International Maritime Organization number

Port Types

• Port

• Anchorage

• Marina

• Offshore Terminal

• Shelter

• Demolition Yard

• Canal

• Fishing Harbour

Development

Project Structure

datalastic-mcp/
├── src/
│   └── datalastic_mcp/
│       ├── __init__.py
│       ├── __main__.py
│       ├── server.py        # MCP server implementation
│       ├── api_client.py    # Datalastic API wrapper
│       └── cache.py         # Caching layer
├── tests/
│   ├── __init__.py
│   ├── test_cache.py        # Cache tests (9 tests)
│   └── test_api_client.py   # API client tests (15 tests)
├── pyproject.toml
├── README.md
└── datalastic_api_key.txt  # Your API key (gitignored)

Running Tests

# Install dev dependencies
pip install pytest pytest-asyncio

# Run all tests
python3 -m pytest tests/ -v

# Run specific test file
python3 -m pytest tests/test_cache.py -v

# Run with coverage
python3 -m pytest tests/ --cov=src/datalastic_mcp

Test Results: All 24 tests passing ✅

• Cache functionality: 9/9 tests

• API client: 15/15 tests

API Documentation

For more information about the Datalastic API, visit:

• API Reference: https://datalastic.com/api-reference/

• Website: https://datalastic.com/

License

This project is provided as-is for use with the Datalastic API.

Documentation

This repository includes several documentation files for different audiences:

• USER_GUIDE.md - Comprehensive guide for end users

  • What is MCP and how it works

  • All 7 tools explained with examples

  • Step-by-step setup for Claude Desktop

  • Usage examples and troubleshooting

  • Start here if you're new!

• README.md (this file) - Quick reference for developers

  • Feature overview and API endpoints

  • Installation and configuration

  • Tool parameters and examples

Support

For issues with:

• This MCP server: Open an issue in this repository

• Datalastic API: Contact Datalastic support at https://datalastic.com/

• MCP protocol: See https://modelcontextprotocol.io/