datalastic-mcp by robderstadt - MCP Server

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 (5 minutes)
Complete Guide: See (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)

Installation

Prerequisites

Python 3.10 or higher
A Datalastic API key (get one at https://datalastic.com/)

Setup

Install dependencies:

pip install mcp httpx pydantic

Or if using the repository:

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

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:

- 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!
(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/