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.
- Find your Signal K address. It usually looks like
http://your-boat:3000. Note the host name (or IP) and port. - 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):The next step wires this command into your assistant. (Prefer to build from source? See Develop below.)npx -y kip-mcp-server - 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.
- Ask it to help. Say something like "Look at my boat's data and suggest some KIP dashboards." Review the previews it shows you.
- 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.jsonfile 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_dashboardprompt drives it, backed by a deterministiccheck_dashboard_uxlint. - 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
--doctorcheck. - 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.