Skip to content

armgit / kaneo

Public Imported from GitHub
0

⚡ Project management that doesn't become the project. Boards, Gantt charts, and GitHub integration. Self-host it or use Kaneo Cloud.

6.5 KB
Raw Blame

Kaneo MCP server

@kaneo/mcp is the official MCP (Model Context Protocol) server for Kaneo. It is maintained in the usekaneo/kaneo monorepo and published to npm by the Kaneo team.

It runs over stdio, signs in with Kaneo's device flow, and then calls the Kaneo API with a bearer token. The package lives in packages/mcp in this monorepo and exposes the kaneo-mcp CLI.

Tip: Every Kaneo instance also ships a built-in HTTP MCP endpoint at /api/mcp. If your MCP client supports Streamable HTTP transport (e.g. Claude Code), you can connect directly without this package. See the MCP docs for details.

Prerequisites

  • Node.js 24+
  • A running Kaneo API (for example http://localhost:1337) and web app (for device approval UI).

Kaneo allows kaneo-cli and kaneo-mcp by default, so you usually do not need extra server configuration.

If you want to run this server with a different client ID, allow it on the Kaneo server:

DEVICE_AUTH_CLIENT_IDS=kaneo-cli,kaneo-mcp,your-client-id

Environment

Variable Description
KANEO_API_URL Kaneo API origin (default http://localhost:1337). Do not include /api.
KANEO_MCP_CLIENT_ID Device-flow client id (default kaneo-mcp). Must match DEVICE_AUTH_CLIENT_IDS on the server.
KANEO_API_KEY Optional. A Kaneo API key (create one under Settings → Account → Developer). When set, the server authenticates with it as a Bearer token and skips the interactive device flow. Use this for headless/Docker setups.

Install

Recommended (no global install): run the interactive installer with npx:

npx @kaneo/mcp

npm downloads the package, then an interactive menu (arrow keys + Enter) asks where to register the server (Cursor user-wide, Cursor project, Claude Desktop, or a custom JSON path). It then merges a mcpServers entry that points at this package’s dist/index.js with your current Node binary.

In a normal terminal, npx @kaneo/mcp and kaneo-mcp with no subcommand both start the installer. When the process is not attached to a TTY (for example when Cursor launches the MCP server with a pipe), the same entry runs the stdio MCP server instead.

To run the server manually from a shell (for example to debug stdio), use:

npx @kaneo/mcp serve

If you prefer a global install:

npm install -g @kaneo/mcp
kaneo-mcp

(kaneo-mcp install is the same installer with an explicit subcommand.)

Non-interactive example (Cursor user config, skip overwrite prompts):

kaneo-mcp install --target cursor-user -y

Point at a self-hosted API when generating the config:

kaneo-mcp install --target cursor-user -y --api-url https://kaneo.example.com

See all options:

kaneo-mcp install --help

If you are currently inside the local packages/mcp package directory, npm may resolve the local workspace package instead of the published one and fail to expose the bin. In that case, either run npx from outside packages/mcp, or use a local build:

node dist/index.js

The published package includes dist/. prepublishOnly runs the build before publish.

Develop from source

From the repo root:

pnpm install
pnpm --filter @kaneo/mcp run build
pnpm --filter @kaneo/mcp run start
pnpm --filter @kaneo/mcp run test

Or run it from the package directory:

pnpm -C packages/mcp run build

The CLI entry points to ./dist/index.js. Use npx @kaneo/mcp or kaneo-mcp after a global install so your IDE config points at the resolved path.

Authentication

On the first tool call that needs Kaneo, the server:

  1. Requests a device code from POST /api/auth/device/code
  2. Prints the verification URL and user code to stderr
  3. Tries to open the browser
  4. Polls POST /api/auth/device/token until approved
  5. Stores the access token at ~/.config/kaneo-mcp/credentials.json with mode 0600

Non-interactive (API key)

For headless or sandboxed environments where opening a browser is impractical, set KANEO_API_KEY to a key created under Settings → Account → Developer. The server sends it as a Bearer token on every request and skips the device flow entirely, so no token is cached to disk.

Tools

  • Session: whoami, list_workspaces, list_workspace_members, list_notifications
  • Search: search
  • Projects: list_projects, get_project, create_project, update_project, list_project_columns
  • Tasks: list_tasks, get_task, get_task_by_ticket_id, create_task, update_task, delete_task, move_task, update_task_status, update_task_assignee, update_task_due_date, update_task_recurrence, list_task_activity
  • Custom fields: list_project_custom_fields, get_task_custom_field_values, set_task_custom_field_value
  • Time entries: list_task_time_entries, get_time_entry, create_time_entry, update_time_entry
  • Comments: list_task_comments, create_task_comment, update_task_comment, delete_task_comment
  • Labels: list_workspace_labels, create_label, attach_label_to_task, detach_label_from_task, delete_label
  • Task relations: create_task_relation, get_task_relations, delete_task_relation

Call list_project_columns before setting a status: the column slugs it returns are the values create_task and update_task_status accept. Call get_task_by_ticket_id with a key such as KAN-12 to retrieve one task without listing a project. If the same key identifies multiple accessible tasks, pass workspaceId or projectId to select one. list_workspace_members resolves the user IDs the assignee tools expect. Time entries have no delete endpoint on the API, so there is no delete_time_entry tool. Call list_project_custom_fields for the field IDs and options set_task_custom_field_value expects. Pass multiselect values as an array of options, dates as YYYY-MM-DD, and null to clear a value.

Releasing

Bump version in packages/mcp/package.json and merge to main. The publish workflow runs the package tests, publishes the new version to npm, and creates a mcp-v<version> GitHub release. Nothing is published while the version stays the same, so tool changes reach npm only once the version is bumped.

Publishing a GitHub release manually also works: tag it mcp-v<version> with the tag version matching packages/mcp/package.json on the tagged commit.