danieldaum.net / kaneo
kaneo (minimalist kanban) fork to experiment adding a tangled integration github.com/usekaneo/kaneo
0
fork

Configure Feed

Select the types of activity you want to include in your feed.

kaneo / packages / mcp /
at main 1 folder 5 files
src
LICENSE
README.md
package.json
tsconfig.json
vitest.config.ts
README.md

Kaneo MCP server#

@kaneo/mcp is a local stdio MCP server for Kaneo.

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 20+
  • 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.

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

Tools#

  • Session: whoami, list_workspaces
  • Projects: list_projects, get_project, create_project, update_project
  • Tasks: list_tasks, get_task, create_task, update_task, move_task, update_task_status
  • Comments: list_task_comments, create_task_comment
  • Labels: list_workspace_labels, create_label, attach_label_to_task, detach_label_from_task