SignalK MCP Server

A Model Context Protocol (MCP) server that provides AI agents with efficient access to SignalK marine data using code execution in V8 isolates. This approach reduces token usage by 90-96% compared to traditional MCP tools.

> 🚀 Version 1.0.6: Now using code execution engine for massive token savings! See CHANGELOG.md for details.

Why Code Execution?

Traditional MCP tools return ALL data to the AI, consuming massive amounts of tokens. This server uses V8 isolates (like Cloudflare Workers) to let AI agents run JavaScript code that filters data before returning it.

Token Savings:
- Vessel state queries: 94% reduction (2,000 → 120 tokens)
- AIS target filtering: 95% reduction (10,000 → 500 tokens)
- Multi-call workflows: 97% reduction (13,000 → 300 tokens)

Quick Start

$3

``bash


Via npx (recommended)

npx signalk-mcp-server

Or install globally

npm install -g signalk-mcp-server
`

$3

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

`json
{
"mcpServers": {
"signalk": {
"command": "npx",
"args": ["signalk-mcp-server"],
"env": {
"SIGNALK_HOST": "localhost",
"SIGNALK_PORT": "3000",
"SIGNALK_TLS": "false"
}
}
}
}
`

$3

AI Agent Query: "What's my vessel's position and the 3 closest AIS targets?"

Code Execution (Automatic):
`javascript
(async () => {
// Get vessel position
const vessel = await getVesselState();
const position = vessel.data["navigation.position"]?.value;

// Get AIS targets and filter in isolate
const ais = await getAisTargets({ pageSize: 50 });
const closest = ais.targets.slice(0, 3);

return JSON.stringify({ position, closest });
})()
// Returns: ~300 tokens (97% savings vs legacy tools!)
`

Features

$3

- V8 Isolate Sandbox: Secure JavaScript execution
- Client-side Filtering: Process data before returning to AI
- Multiple API Calls: Combine operations in one execution
- 90-96% Token Savings: Massive reduction in context window usage
- Sub-100ms Overhead: Fast execution with memory/timeout limits

$3

When using execute_code, these functions are available. IMPORTANT: ALL functions are async and MUST be awaited:

`javascript
// Vessel data
const vessel = await getVesselState();

// AIS targets (with pagination and optional distance filter)
const ais = await getAisTargets({ page: 1, pageSize: 50, maxDistance: 5000 });

// System alarms
const alarms = await getActiveAlarms();

// Discover available data paths
const paths = await listAvailablePaths();

// Get specific path value (both string and object syntax work)
const speed = await getPathValue("navigation.speedOverGround");
const heading = await getPathValue({ path: "navigation.headingTrue" });

// Connection status - ALSO requires await!
const status = await getConnectionStatus();
`

$3

- Vessel position, heading, speed, wind
- AIS target tracking with distance calculations
- System notifications and alarms
- Dynamic SignalK path discovery
- Connection health monitoring

Configuration

$3

`env


SignalK Connection (Required)

SIGNALK_HOST=localhost # SignalK server hostname/IP
SIGNALK_PORT=3000 # SignalK server port
SIGNALK_TLS=false # Use WSS/HTTPS (true/false)

Execution Mode (Optional)

EXECUTION_MODE=code # code (default) | tools (legacy) | hybrid

Optional Settings

SERVER_NAME=signalk-mcp-server
SERVER_VERSION=1.0.6
`

$3

| Mode | Description | Use Case |
|------|-------------|----------|
| code (default) | V8 isolate execution only | Production use, maximum efficiency |
| tools | Legacy MCP tools | Backward compatibility |
| hybrid | Both approaches available | Migration period |

Examples

$3

Query: "Get my vessel name and position"

Code:
`javascript
(async () => {
const vessel = await getVesselState();
return JSON.stringify({
name: vessel.data.name?.value,
position: vessel.data["navigation.position"]?.value
});
})()
`

Result: ~200 tokens (vs 2,000 with legacy tools)

$3

Query: "Show vessels within 1 nautical mile"

Code:
`javascript
(async () => {
const ais = await getAisTargets({ pageSize: 50 });

// Filter in isolate - huge savings!
const nearby = ais.targets.filter(t =>
t.distanceMeters && t.distanceMeters < 1852
);

return JSON.stringify({
total: ais.count,
nearby: nearby.length,
vessels: nearby.slice(0, 5)
});
})()
`

Result: ~300 tokens (vs 10,000 with legacy tools)

$3

Query: "Any critical alarms?"

Code:
`javascript
(async () => {
const alarms = await getActiveAlarms();

const critical = alarms.alarms.filter(a =>
a.state === "alarm" || a.state === "emergency"
);

return JSON.stringify({
hasCritical: critical.length > 0,
count: critical.length,
details: critical
});
})()
`

Result: ~100 tokens (vs 1,000 with legacy tools)

$3

Query: "Give me a situation report"

Code:
`javascript
(async () => {
// All calls in ONE execution!
const vessel = await getVesselState();
const ais = await getAisTargets({ pageSize: 50 });
const alarms = await getActiveAlarms();

// Process everything in isolate
const closeVessels = ais.targets.filter(t =>
t.distanceMeters && t.distanceMeters < 1852
).length;

const criticalAlarms = alarms.alarms.filter(a =>
a.state === "alarm" || a.state === "emergency"
).length;

return JSON.stringify({
position: vessel.data["navigation.position"]?.value,
speed: vessel.data["navigation.speedOverGround"]?.value,
vesselsNearby: closeVessels,
criticalAlarms: criticalAlarms
});
})()
`

Result: ~300 tokens (vs 13,000 with 3 separate tool calls!)

Development

$3

- Node.js 18.0.0 or higher
- Access to a SignalK server

$3

`bash


Clone repository

git clone
cd signalk-mcp-server

Install dependencies

npm install

Build

npm run build

Run tests

npm run test:unit

Run in development mode

npm run dev
`

$3

`bash


Unit tests (fast)

npm run test:unit

Integration tests (requires live SignalK server)

npm run test:e2e

Full CI pipeline

npm run ci
`

Architecture

$3

`
AI Agent
↓
execute_code tool
↓
V8 Isolate Sandbox (isolated-vm)
↓
SignalK SDK Functions (all async, must await)
↓
SignalK Binding Layer (RPC-style)
↓
SignalK Client (HTTP REST API)
↓
SignalK Server
`

> Note: HTTP-only mode ensures fresh data on every request. WebSocket code is preserved for future streaming support.

$3

- Isolate Sandbox (src/execution-engine/isolate-sandbox.ts): Secure V8 isolate execution
- SignalK Binding (src/bindings/signalk-binding.ts): RPC-style method invocation
- SDK Generator (src/sdk/generator.ts): Auto-generates SDK from tool definitions
- SignalK Client (src/signalk-client.ts): HTTP/WebSocket client for SignalK

$3

- Complete Isolation: No access to Node.js globals
- Memory Limits: 128MB per execution
- Timeout Protection: 30s maximum execution time
- No Credential Exposure: SignalK auth handled by binding layer
- Read-Only: No write operations to SignalK server

Migration from 1.x

$3

Version 1.0.6 changes the default mode from hybrid to code. Legacy tools are no longer available by default.

$3

To use legacy tools, set the execution mode:

`json
{
"mcpServers": {
"signalk": {
"env": {
"EXECUTION_MODE": "tools"
}
}
}
}
`

$3

See TOOL-MIGRATION-GUIDE.md for complete migration examples.

Before (Legacy):
`
Tool: get_vessel_state
Returns: All vessel data (~2000 tokens)
`

After (Code):
`javascript
(async () => {
const vessel = await getVesselState();
return JSON.stringify({
name: vessel.data.name?.value,
position: vessel.data["navigation.position"]?.value
});
})()
// Returns: ~200 tokens
`

Troubleshooting

$3

Check connection status (note: await is required):
`javascript
(async () => {
const status = await getConnectionStatus(); // await is required!
return JSON.stringify(status);
})()
`

$3

If you need legacy tools temporarily:
`bash
EXECUTION_MODE=tools npx signalk-mcp-server
`

$3

Enable verbose logging:
`env
DEBUG=true
LOG_LEVEL=debug
``

Contributing

Contributions welcome! Please see CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE for details.

Resources

- SignalK Documentation
- Model Context Protocol
- CHANGELOG.md - Version history and migration guide
- TOOL-MIGRATION-GUIDE.md - Detailed migration examples
- Claude Desktop MCP Docs

Credits

Built with:
- isolated-vm - V8 isolate execution
- @modelcontextprotocol/sdk - MCP TypeScript SDK
- SignalK community for the excellent marine data protocol

---

🚢 Happy sailing with AI-powered marine data!