# killBottleneck MCP server

> Lets AI assistants build and edit goal, process and organisation maps on a self-hosted instance via a built-in MCP server.

- Repository: https://github.com/tengolabs/killbottleneck
- Page: https://hostedmcp.org/servers/tengolabs/killbottleneck
- Transport: stdio
- Stars: 14
- License: MIT
- Latest version: 1.0.0

## Install

### Claude Code

```sh
claude mcp add --env 'KB_API_KEY=<YOUR_KB_API_KEY>' --env 'KB_URL=<KB_URL>' killbottleneck -- npx -y killbottleneck-mcp
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "killbottleneck": {
      "command": "npx",
      "args": [
        "-y",
        "killbottleneck-mcp"
      ],
      "env": {
        "KB_API_KEY": "<YOUR_KB_API_KEY>",
        "KB_URL": "<KB_URL>"
      }
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "killbottleneck": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "killbottleneck-mcp"
      ],
      "env": {
        "KB_API_KEY": "<YOUR_KB_API_KEY>",
        "KB_URL": "<KB_URL>"
      }
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"killbottleneck","type":"stdio","command":"npx","args":["-y","killbottleneck-mcp"],"env":{"KB_API_KEY":"<YOUR_KB_API_KEY>","KB_URL":"<KB_URL>"}}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "killbottleneck": {
      "command": "npx",
      "args": [
        "-y",
        "killbottleneck-mcp"
      ],
      "env": {
        "KB_API_KEY": "<YOUR_KB_API_KEY>",
        "KB_URL": "<KB_URL>"
      }
    }
  }
}
```

### Codex

```sh
codex mcp add killbottleneck --env 'KB_API_KEY=<YOUR_KB_API_KEY>' --env 'KB_URL=<KB_URL>' -- npx -y killbottleneck-mcp
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.killbottleneck]
command = "npx"
args = ["-y", "killbottleneck-mcp"]

[mcp_servers.killbottleneck.env]
KB_API_KEY = "<YOUR_KB_API_KEY>"
KB_URL = "<KB_URL>"
```

### Gemini CLI

```sh
gemini mcp add -s user -e 'KB_API_KEY=<YOUR_KB_API_KEY>' -e 'KB_URL=<KB_URL>' killbottleneck npx -- -y killbottleneck-mcp
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "killbottleneck": {
      "command": "npx",
      "args": [
        "-y",
        "killbottleneck-mcp"
      ],
      "env": {
        "KB_API_KEY": "<YOUR_KB_API_KEY>",
        "KB_URL": "<KB_URL>"
      }
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `KB_API_KEY` | yes | yes | API key issued in the app (user menu -> API keys). Use a read-write scope for editing. |
| `KB_URL` | yes | no | Address of your killBottleneck instance, e.g. https://company.killbottleneck.com or http://192.168.1.10:8090 |
| `KB_AGENT_TIMEOUT_MIN` | no | no |  |
| `KB_ALLOW_PRIVATE_WEBHOOKS` | no | no |  |
| `KB_AUTO_HOUR` | no | no |  |
| `KB_GOOGLE_CLIENT_ID` | no | no |  |
| `KB_GOOGLE_CLIENT_SECRET` | no | no |  |
| `KB_PUBLIC_URL` | no | no |  |

## Tools (35)

- `list_maps`: List goal maps the key owner can see — own, team and shared maps (id, title, node count, last update, access: owner/edit/work/read). Use archived=true to list archived maps instead.
- `get_map`: Read one map as an indented tree with node ids, statuses ([✓] done, [~] in progress, [ ] todo), deadlines and owners. The header shows the key's access level (owner/edit = full write; work and read = only the status of the key owner's own nodes, like ticking off in the app). Always call this before modifying a map you have not read yet.
- `create_map`: Create a new goal map from an outline. The map gets an apex (root goal) from `title`/`apex_text`; `outline` items become nested nodes. Layout is computed automatically. Max 200 nodes per call. Returns the created tree with node ids.
- `update_map`: Rename a map or change its description (the project as a whole — not the apex node; the list of maps and the database show this title). Only `title` and `description`; archiving or the map style stay with people in the app. Requires full write access to the map.
- `add_nodes`: Add a subtree of nodes to an existing map under parent_id (or under the apex when parent_id is omitted). A node is a goal; a node with an assignee (owner) OR a deadline IS a task — that is the only kind of task in killBottleneck (there is no separate task record; new work = new node). NOTE: this re-computes the layout of the whole map. Max 200 nodes per call. Returns the updated tree.
- `update_node`: Update fields of one node: title, status (todo/in_progress/done), description, deadline (YYYY-MM-DD, empty string clears), planned_on (YYYY-MM-DD, today to +7 days, empty string clears — WHEN the key owner plans to work on it; this is how killBottleneck expresses priority, never by moving the deadline), owner (e-mail, empty string clears), wait_for_children, colour, icon (one emoji), who performs it (executor_kind / executor_name) and the automation wish (automation_wanted / automation_note). Unknown fields are rejected with the list of allowed ones. Marking status done may unblock waiting nodes, notify their owners and trigger automations on them.
- `delete_node`: Delete a node INCLUDING its whole subtree. The apex (root) cannot be deleted and whole maps cannot be deleted via the API. Irreversible — read the map first and double-check the node id.
- `create_rule`: Create an automation rule on a map: WHEN trigger fires (and optional AND conditions match) DO the actions in order. Rules run for changes made in the UI, via API and by agents alike. Structural limits: 50 rules per map, 10 actions, 20 conditions — there is NO monthly run quota. A rule applies only to future events, never retroactively. node_id scopes the rule to one node (required for schedule rules whose actions target a node).
- `list_rules`: List automation rules of a map: id, name, enabled, scope node, trigger, conditions, actions, last_fired and last_error (a non-empty last_error means the rule is misconfigured and its owner was notified).
- `update_rule`: Update an automation rule. Pass only `enabled` to toggle it on/off; otherwise pass the FULL new shape (name, trigger, actions, optional conditions/node_id) — partial field edits are not merged. Edits apply to future events only and clear the rule's error state.
- `delete_rule`: Delete an automation rule. Its run log stays (with the rule name snapshot). Irreversible.
- `list_rule_runs`: Read the run log of a map's automation rules (newest first, max 100): what fired, on which node, ok/failed/skipped and what the actions did. skipped = a safety stop (rule chain depth or per-save cap), detail says which.
- `list_rule_templates`: List the instance-wide library of rule templates (shape of a rule without a map or node scope). To use one, read it and call create_rule on the target map with its trigger/conditions/actions — the created rule is an independent copy.
- `save_rule_template`: Save a rule shape into the instance-wide template library (create, or update with template_id — only the author or an admin may update). Templates carry no map and no node scope; create_subnodes may only use parent=trigger_node. Template names are unique.
- `delete_rule_template`: Delete a rule template from the library (author or admin only). Rules already created from it are independent copies and stay untouched.
- `get_org_structure`: Read the organization structure (the org map): positions and functions with node ids, holders and deputies. Use the node ids as dynamic rule targets "position:<nodeId>" / "deputy_of_position:<nodeId>". Read-only — holders and deputies are appointed by an admin in the app.
- `list_people`: List the people work can be assigned to: instance members (e-mail, display name, role) and external contacts visible to the key owner (their owner_email is a pseudo e-mail usable as owner). Use these e-mails as `owner` in create_map/add_nodes/update_node and in set_owner rules — an unknown e-mail is rejected. Read-only.
- `get_portfolio`: Read the portfolio overview across all team and shared maps the key owner can read (private maps are excluded, exactly like the Organization page): per-project completion, overdue and stuck items, people with overdue work and a 7-day change summary. Optional today=YYYY-MM-DD. Read-only.
- `create_event`: Create a calendar EVENT with a time (meeting, call, dentist…) — NOT a task and not part of any map. Personal by default; `calendar` (a name from list_calendars) puts it into a SHARED calendar: company events (kind shared), a room/car booking (kind resource — needs time; end_time defaults to +60 min; an overlapping booking is refused and the error names the next free slot) or time off (kind absence — all-day, end_day for a range, participants = who is away, default the key owner). Optional participants (e-mails of instance members from list_people; each sees the event in their calendar) and a reminder N minutes before (in-app + e-mail). Times are the instance's local time.
- `create_events`: Create SEVERAL calendar events at once — e.g. every date of a lecture schedule, a seminar invitation or a training plan ("every Tuesday until January" = list each date). All or nothing: when one item is invalid nothing is written and the error names the item. An event that is already in the calendar (same title, day and time) is skipped and reported. calendar, participants and remind_before_min apply to all items. Max 30 items; time off goes one by one via create_event.
- `update_event`: Change an existing event by id: your own, one in a shared calendar as admin/manager, or your own time off. Only the given fields change; an empty string clears time, end_day, end_time or calendar (calendar "" = make it personal). Moving `day` of a multi-day event keeps its length. participants replaces the whole list; remind false cancels the reminder.
- `delete_event`: Delete an event by id (your own, or one in a shared calendar as admin/manager). If you were only invited, you leave the event instead and it stays for the others.
- `list_events`: List the calendar events the key owner sees — own, invited, and every event of the shared calendars — in a day range; default today−365 … +730. A multi-day event counts when it overlaps the range. Optional calendar = only that shared calendar. Read-only.
- `list_calendars`: List the shared calendars of the instance — company events (shared), rooms and other bookable things (resource), vacations and time off (absence) — with kind, color, who may add entries (write_access) and whether time off needs approval. Read-only.
- `create_calendar`: Create a shared calendar (admin or manager only): kind shared = company events, resource = a room, car or other bookable thing (overlapping bookings are refused), absence = vacations and time off (needs_approval makes new entries wait for an admin/manager decision). visibility all = the whole team sees it (default); members = only the listed members (e-mails from list_people), and the creator — like a project shared with chosen people (an admin who is not listed does not see it either). write_access admins limits new entries to admins and managers. Archive a calendar to keep its history; delete_calendar removes it with all its events.
- `delete_calendar`: Delete a shared calendar by id or name together with ALL its events (admin or manager only). Cannot be undone — prefer archiving (not offered here) when the history should stay.
- `who_is_away`: Who is away — time off from absence calendars that is approved or not subject to approval (pending and rejected requests are excluded) — in a day range; default today … +14. One line per person and absence. Read-only.
- `create_reminder`: Set a timed REMINDER for a map node relative to its deadline: offset_days before the deadline (0 = on the deadline day, 1 = the day before) at time HH:MM, instance local time. One reminder per person and node (calling again replaces it). Does NOT change the deadline; the node must already have one (set it with update_node first). Private to the key owner.
- `list_pages`: List the key owner's pages — single-file HTML artifacts (presentations, overviews, small apps) created by the assistant or an agent: id, title, status (ceka = queued, pise = being written, hotovo = ready, chyba = failed), size, public link, team visibility.
- `get_page`: Read one page (page_id from list_pages): its metadata and the full HTML. Read it before changing a page with update_page.
- `generate_image`: Draw a picture (illustration, banner, header image, poster) with the instance's image model and return a public link to the JPEG. Write `prompt` in English as a detailed visual description and add "no text". Only when readable words must be in the picture, put the exact short text into `text` (only if the instance allows pictures with text; letters may come out wrong). format: square 1024×1024 (default), banner 1200×400, header 1536×640, portrait 512×896, landscape 1792×1024. Costs AI credits like an assistant message.
- `create_page`: Create a page from a COMPLETE single-file HTML document you wrote yourself (inline CSS/JS; external libraries only from https CDNs; no fetch to other servers; size limit per instance, typically 300 kB). The page appears in the user's Pages panel in the app and runs sandboxed (no access to the app's session). team_visible=true shows it to all members of the organization. Returns the id and the public link if one is on.
- `update_page`: Replace the HTML and/or the title of an existing page (page_id from list_pages). Send the WHOLE new document, not a diff; the previous version is kept and the user can restore it.
- `share_page`: Change sharing of a page: link_on = public link for anyone with the link (no account needed), link_off = turn it off, link_new = replace the link (the old one stops working), team_on / team_off = show or hide the page for all members of the organization, user_on / user_off = share with / unshare from one named member (pass `email`; members come from list_people). Returns the current public link and the people it is shared with.
- `delete_page`: Delete a page for good (page_id from list_pages). Cannot be undone.

## FAQ

### How do I connect killBottleneck to Claude Desktop or Claude Code?

Create an API key with read (or read and write) scope in the app under user menu → API keys, then register the killbottleneck-mcp package with your assistant; npx fetches it on first use.

### Do I need to install anything for the killBottleneck MCP server?

No. The server is published on npm as killbottleneck-mcp and npx downloads it on first use, though you can also run it from the repository with node.

### How is killBottleneck authenticated for MCP access?

Access uses API keys created in the app, with a read-only or read-and-write scope; the token is shown only once and can be given an expiry.

### Can the MCP server work with a self-hosted instance?

Yes, it behaves the same for self-hosted and hosted instances; only the server address differs.

### What can an AI assistant do through the killBottleneck MCP server?

It can build maps from meeting notes conversationally, make bulk edits and tick off completed items.
