kip-mcp-server

kip-mcp-server

    

An MCP server that lets an AI assistant (such as Claude, Codex, or Gemini) look at your boat's Signal K data and help you design and install KIP dashboards — the gauges and panels you see on your chartplotter or tablet.

You stay in control: the assistant shows you a picture of each dashboard first, and it only saves anything to your boat after you say yes.

What it does

• Looks at your boat's data. It finds the values your boat reports through Signal K

— speed, wind, depth, batteries, engine, and so on.

• Suggests dashboards. It proposes a general dashboard plus ones for specific jobs:

sailing, motoring, power, anchoring, navigation, and weather.

• Shows you a preview. You see a simple picture of each dashboard before anything is

saved.

• Installs them — with your OK. It writes the dashboards to your KIP setup, or hands

you a file you can import yourself.

What it looks like

A short session with an AI assistant, after pointing it at your boat:

You:  Look at my boat's data and suggest some KIP dashboards.

  → analyze_signalk_data            142 paths · speed, wind, depth, battery, engine
  → recommend_dashboard_set         6 dashboards the data supports

Assistant: Your boat reports navigation, wind, depth, electrical and engine data,
so I can build these. Here's the "Sailing" one — a preview, nothing saved yet:

  ┌─────────────┬─────────────┬───────────────────────────┐
  │ SOG  6.2 kn │ AWS 14 kn   │                           │
  ├─────────────┼─────────────┤        wind steering       │
  │ DPT  8.4 m  │ AWA  42°    │                           │
  └─────────────┴─────────────┴───────────────────────────┘

You:  Looks good — install the sailing and anchor ones.

  → apply_kip_config (dry run)      2 dashboards → KipConfig (global)
Assistant: This will add "Sailing" and "Anchor" to KIP. Go ahead?
You:  Yes.
  → apply_kip_config                written ✓  — open KIP to see them.

The assistant always shows a preview first and asks before writing anything to your boat.

Quick start (for boat owners)

You need a Signal K server running on your boat (or on your network), with KIP installed.

1. Find your Signal K address. It usually looks like http://your-boat:3000. Note

the host name (or IP) and port.

1. Get this server. You don't need to install anything by hand — your AI assistant can

run it on demand with npx (which comes with Node.js 24 or newer): ``bash npx -y kip-mcp-server `` The next step wires this command into your assistant. (Prefer to build from source? See Develop below.)

1. Connect it to your AI assistant. Pick your assistant in docs/clients

and follow the short setup there. You tell the assistant your boat's host and port.

1. Ask it to help. Say something like *"Look at my boat's data and suggest some KIP

dashboards."* Review the previews it shows you.

1. Say yes. When you're happy, tell it to go ahead. It asks before writing anything.

If your Signal K server is older, it gives you a KipConfig.json file to import from KIP's Settings instead.

How to connect it

The server reads a few settings from its environment:

| Setting | What it is | Default | | --- | --- | --- | | SIGNALK_HOST | Your Signal K host name or IP | localhost | | SIGNALK_PORT | Your Signal K port | 3000 | | SIGNALK_TLS | Set to true if your server uses https | false | | SIGNALK_TOKEN | A Signal K login token, needed to write dashboards | (none) | | SIGNALK_USER | A Signal K username — used with SIGNALK_PASSWORD instead of a token | (none) | | SIGNALK_PASSWORD | The matching Signal K password | (none) | | KIP_URL | Override where KIP is served, if it's not the default | (derived) |

Reading your data needs no login. Writing dashboards to the server needs either a token or a username and password; you can always use the file-export option instead, which needs nothing extra. For how to get a token (or why a username/password is simpler), see Signal K authentication.

Remote access over HTTP (optional, advanced)

By default the server talks over stdio — the assistant runs it as a local subprocess. There is also an optional HTTP mode (kip-mcp-http) for hosting the server so a remote assistant (such as Claude.ai) can reach it over the network. It is opt-in and meant for a single operator behind a reverse proxy that adds TLS.

# Behind a TLS-terminating reverse proxy that forwards to 127.0.0.1:3017
MCP_BEARER_TOKEN=a-long-random-secret \
MCP_PUBLIC_URL=https://boat.example.com/mcp \
  npx kip-mcp-http

| Setting | What it is | Default | | --- | --- | --- | | HTTP_HOST | Address to bind | 127.0.0.1 (loopback) | | HTTP_PORT | Port to listen on | 3017 | | HTTP_PATH | URL path for the MCP endpoint | /mcp | | MCP_BEARER_TOKEN | One or more (comma-separated) bearer tokens that callers must present | (none) | | MCP_PUBLIC_URL | The public URL clients reach, used for the Host allowlist and metadata | (derived) | | MCP_ALLOWED_ORIGINS | Comma-separated browser origins to accept (off by default) | (none) | | MCP_ALLOWED_HOSTS | Override the Host allowlist | (derived) | | MCP_ALLOW_INSECURE | Set to true to start anyway in an unsafe setup | (unset) |

Every request must present a valid Authorization: Bearer <token> and pass a Host/Origin allowlist before it reaches the MCP layer. The server refuses to start if it would bind to a non-loopback address or run without a bearer token, unless you set MCP_ALLOW_INSECURE=true. It uses one Signal K login for all sessions, so treat it as a single-tenant deployment; the same SIGNALK_* settings above apply.

What the assistant can do

The server gives the assistant a set of tools, grouped by job:

• Look at the boat — list the data paths, their units, and which plugins are installed.
• Know KIP's parts — list every KIP widget and how it's configured, plus the colours,

icons and units KIP understands.

• Design dashboards — suggest a set of dashboards, build one for a chosen job, and draw

a preview.

• Review the UX — critique a dashboard for marine usability (hierarchy, grouping,

consistency, labels) with severity-tagged findings; the review_dashboard prompt drives it, backed by a deterministic check_dashboard_ux lint.

• Check and save — check a dashboard is well-formed, export it to a file, or write it to

the boat (asking first).

More help

• Recipes — worked examples of asking the assistant to design dashboards.
• Troubleshooting — fixes for the common problems, starting with

the built-in --doctor check.

• Tool reference — every tool and prompt the assistant can use.

Glossary

A few terms, in plain words:

• Signal K — the open system many boats use to share data (speed, wind, depth, …) over

the network.

• path — the name of one piece of data, like navigation.speedOverGround (speed over

ground).

• KIP — the app that shows your boat's data as dashboards of gauges and panels.
• widget — one gauge or panel on a dashboard (a number, a dial, a wind display, …).
• dashboard — a screen full of widgets, laid out on a grid.
• token — like a password for software: it lets the server save changes to your boat.
• dry run — the assistant tells you what it would do, without actually doing it. Saving

is a dry run by default.

Develop

This project uses Node.js 24 (LTS). Common commands:

npm install        # install dependencies
npm run typecheck  # check types
npm run lint       # check code style
npm test           # run the tests
npm run build      # compile to dist/
npm run smoke      # start the built server and check it answers
npm run ci         # run the full set of checks

For a full guide to running and testing the server locally during development — pointing an AI client or the MCP Inspector at a local build, running the HTTP transport, and testing against Signal K (or offline) — see docs/development.md.

Commits follow Conventional Commits; releases and version numbers are produced automatically from those commit messages.

License

MIT — see LICENSE.