SignalK MCP Server

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

🚀 Version 1.0.6: Now using code execution engine for massive token savings! SeeCHANGELOG.mdfor details.

# Via npx (recommended) npx signalk-mcp-server # Or install globally npm install -g signalk-mcp-server

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

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

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

- 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

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

// 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();

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

# 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

Query:"Get my vessel name and position"

(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)

Query:"Show vessels within 1 nautical mile"

(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)

(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)

Query:"Give me a situation report"

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

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

# Clone repository git clone <repository-url> 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

# Unit tests (fast) npm run test:unit # Integration tests (requires live SignalK server) npm run test:e2e # Full CI pipeline npm run ci

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.

- 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

- 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

Version 1.0.6 changes the default mode fromhybridtocode. Legacy tools are no longer available by default.

To use legacy tools, set the execution mode:

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

SeeTOOL-MIGRATION-GUIDE.mdfor complete migration examples.

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

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

Check connection status (note:awaitis required):

(async () => { const status = await getConnectionStatus(); // await is required! return JSON.stringify(status); })()

EXECUTION_MODE=tools npx signalk-mcp-server

Contributions welcome! Please seeCONTRIBUTING.mdfor guidelines.

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

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

Fuses biometric signals into a stress score (0-100) for real-time AI adaptation. MCP + A2A native.