Content
# 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](QUICK_START.md) (5 minutes)
- **Complete Guide:** See [USER_GUIDE.md](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:
```bash
pip install mcp httpx pydantic
```
Or if using the repository:
```bash
cd /path/to/datalastic-mcp
pip install -e .
```
2. 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`
```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:
```bash
npx @modelcontextprotocol/inspector python -m datalastic_mcp
```
### Direct Usage
Run the server directly:
```bash
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
```bash
# 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](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](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/
