killbottleneck — Claude Code MCP server: what it does, how to install
Links self-hosted goal and process maps to your coding assistant via MCP. Useful for tracking project blockers and milestones without routing team data to external clouds.
claude mcp add killbottleneck -e KB_URL=<KB_URL> -e KB_API_KEY=<KB_API_KEY> -- npx -y killbottleneck-mcpWhat killbottleneck does
killBottleneck runs on your own infrastructure via Docker, turning projects into visual graphs of goals and dependencies. The assistant connects to this instance through the killbottleneck-mcp package. This setup lets an AI agent inspect work structures directly.
The platform provides a daily task overview alongside built-in time tracking. It operates with zero telemetry by default: fonts load locally, and external calls to language models happen only when explicitly configured in the environment file.
Without a running killBottleneck container and both KB_URL and KB_API_KEY values present, the MCP server will not start.
What it helps with
- inspect project goal maps and task dependencies from the coding assistant
- find overdue or blocking steps directly within the daily plan
- break down project milestones into sub-tasks inside a private instance
- keep company project planning data on your own hardware without external leaks
Example prompts for the agent
- Show all tasks in the current goal map that are blocking other team members.
- List my overdue goals for today from the self-hosted workspace.
- Create intermediate milestones for the database migration node in killBottleneck.
How to install killbottleneck
Platform CLI
claude mcp add killbottleneck -e KB_URL=<KB_URL> -e KB_API_KEY=<KB_API_KEY> -- npx -y killbottleneck-mcpReplace <…> with your own values
Platform CLI
codex mcp add killbottleneck --env KB_URL=<KB_URL> --env KB_API_KEY=<KB_API_KEY> -- npx -y killbottleneck-mcpReplace <…> with your own values
Config file
{
"mcpServers": {
"killbottleneck": {
"command": "npx",
"args": [
"-y",
"killbottleneck-mcp"
],
"env": {
"KB_URL": "<KB_URL>",
"KB_API_KEY": "<KB_API_KEY>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"killbottleneck": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"killbottleneck-mcp"
],
"env": {
"KB_URL": "<KB_URL>",
"KB_API_KEY": "<KB_API_KEY>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e KB_URL=<KB_URL> -e KB_API_KEY=<KB_API_KEY> killbottleneck npx -y killbottleneck-mcpReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about killbottleneck
How to install killbottleneck in Claude Code?
Run claude mcp add killbottleneck -e KB_URL=<KB_URL> -e KB_API_KEY=<KB_API_KEY> -- npx -y killbottleneck-mcp. Replace the placeholders with your instance address and secret key.
What does killbottleneck do?
It connects your coding agent to your self-hosted killBottleneck instance. The agent can then review goal hierarchies, task statuses, and daily priorities while keeping your data local.
What is required before using this MCP server?
You need a running killBottleneck deployment via Docker and an active API token. The server will not launch if KB_URL or KB_API_KEY are missing.
