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.

• 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):

  npx -y kip-mcp-server
  

  The next step wires this command into your assistant. (Prefer to build from source? See Develop below.)
• 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.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.