⚡ Project management that doesn't become the project. Boards, Gantt charts, and GitHub integration. Self-host it or use Kaneo Cloud.
TypeScript honoissue-managementissue-trackerjira-alternativekanbanlinear-alternativemcpproject-managementreactself-hostedtypescript
---
title: Kaneo MCP Server
description: Connect Kaneo to MCP clients like Cursor and Claude Desktop using the official Kaneo MCP server.
---
Kaneo supports the Model Context Protocol (MCP) in two ways:
1. **Built-in HTTP endpoint**: every Kaneo instance exposes `/api/mcp` out of the box. No extra setup, no extra process.
2. **Stdio package** ([`@kaneo/mcp`](https://www.npmjs.com/package/@kaneo/mcp)): the official Kaneo MCP package on npm, a local stdio server for clients that prefer stdio transport.
Both offer the same tools for managing workspaces, projects, tasks, custom fields, comments, and labels.
To work with Kaneo from a terminal or a shell script instead, use the [Kaneo CLI](/cli).
## Built-in HTTP endpoint
Every Kaneo API instance ships with a Streamable HTTP MCP endpoint. This is the recommended approach for self-hosted deployments.
Point your MCP client at:
```
https://your-kaneo-instance.com/api/mcp
```
With an OAuth-capable client, you will be redirected to Kaneo to sign in and explicitly approve the MCP client. After approval, all MCP tools run as your authenticated user.
The endpoint implements OAuth 2.1 with PKCE for authentication. Discovery metadata is available at:
- `/.well-known/oauth-protected-resource/api/mcp`
- `/.well-known/oauth-authorization-server/api`
The endpoint serves both MCP protocol eras without server-side sessions. Modern
`2026-07-28` requests are self-contained; 2025-era clients still send
`initialize`, but Kaneo does not issue a session ID. See [MCP protocol
reference](/core/integrations/mcp-stateless) for transport behavior, proxy
requirements, and request limits.
## Stdio package
The `@kaneo/mcp` package runs a local stdio MCP server and authenticates with Kaneo using device authorization. Use this when your MCP client requires stdio transport.
### Prerequisites
- Node.js 24 or newer
- A running Kaneo API
- Access to the Kaneo web app to approve device login
By default, self-hosted Kaneo allows both `kaneo-cli` and `kaneo-mcp` as device auth client IDs.
### Install and register
Use the recommended interactive installer:
```bash
npx -y @kaneo/mcp
```
The installer lets you choose where to register the server configuration:
- Cursor (user-wide)
- Cursor (project-level)
- Claude Desktop
- Custom JSON config path
You can also run the explicit install command:
```bash
npx -y @kaneo/mcp install --target cursor-user -y
```
Use `--help` to see all available targets and flags:
```bash
npx -y @kaneo/mcp install --help
```
### Point to a self-hosted instance
When generating config, pass your Kaneo base URL:
```bash
npx -y @kaneo/mcp install --target cursor-user -y --api-url https://kaneo.example.com
```
Or set it via environment variable:
| Variable | Description |
| --- | --- |
| `KANEO_API_URL` | Kaneo API base URL. Default: `http://localhost:1337`. A trailing `/api` is accepted and normalized. |
| `KANEO_MCP_CLIENT_ID` | Device auth client ID. Default: `kaneo-mcp`. |
If you override `KANEO_MCP_CLIENT_ID`, make sure it is included in [`DEVICE_AUTH_CLIENT_IDS`](/core/installation/environment-variables).
### Authentication flow
On the first tool call that needs Kaneo access, the MCP server:
1. Requests a device code from Kaneo
2. Prints a verification URL and user code
3. Opens the browser when possible
4. Polls until you approve sign-in
5. Stores credentials in `$XDG_CONFIG_HOME/kaneo-mcp/credentials.json`, or `~/.config/kaneo-mcp/credentials.json` when `XDG_CONFIG_HOME` is unset
## Available tools
Both the HTTP endpoint and stdio package expose the same 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`, `duplicate_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`
Use `get_task_by_ticket_id` with a key such as `KAN-12` to fetch one task directly. If the same key identifies multiple accessible tasks, pass `workspaceId` or `projectId` to select one.
`list_project_columns` is worth calling first when setting a status: the column
slugs it returns are exactly the values `create_task` and `update_task_status`
accept. Likewise `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.
`get_task` and `list_tasks` don't include custom field values. Call
`list_project_custom_fields` for a project's field IDs, types, and options, and
`get_task_custom_field_values` for one task's values. `set_task_custom_field_value`
takes a string, number, or boolean, an array of options for a multiselect field,
or `null` to clear the value. Dates use `YYYY-MM-DD`.
## Debugging
To run the stdio server directly:
```bash
npx -y @kaneo/mcp serve
```
When running from source in this monorepo:
```bash
pnpm --filter @kaneo/mcp run build
pnpm --filter @kaneo/mcp run start
```