datalastic-mcp

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)

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 .

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

Option A: Environment Variable ``bash 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/