Kaneo review: a self-hosted project management tool that ships its own MCP endpoint

What Kaneo actually is, and the team it is written for

Kaneo is an open source project management application written in TypeScript and released under the MIT licence. The README frames the project against what it calls bloated, overcomplicated platforms, and states the belief that the problem with most tools is not missing features but too many of them. That is a positioning statement, and it has a practical consequence: the project's own feature list is short by design, so anyone evaluating it should treat the absence of a feature as intentional until proven otherwise.

The target user is a team that is willing to run its own infrastructure. The README lists self-hosting as a differentiator, and the deployment paths it documents (Docker Compose, Coolify, a Helm chart under charts/kaneo, and a CLI called drim) all assume you have a server and can point a domain at it. There is also a hosted option at cloud.kaneo.app for people who do not want that work, but the repository itself is the self-hosted product.

A second audience is less obvious. Because every instance ships an HTTP MCP endpoint at /api/mcp, Kaneo is also aimed at people who want AI clients to read and write their tasks. That is unusual for a tool this small, and it is probably the most concrete reason to pick Kaneo over a generic kanban board.

How the Docker Compose stack is put together

The repository root contains compose.yml, compose.local.yml, and compose.coolify.yml. The main compose.yml defines two services. One is postgres, using the postgres:16-alpine image, exposing port 5432, with a named volume postgres_data mounted at /var/lib/postgresql/data and a healthcheck that runs pg_isready -U kaneo -d kaneo. The other is kaneo, using ghcr.io/usekaneo/kaneo:latest, exposing port 5173, and declaring a dependency on postgres with the condition service_healthy.

The kaneo service also has its own healthcheck: a wget spider request against http://127.0.0.1:5173/api/health, with a start period of 60 seconds and three retries. That start period is worth noting when you debug a slow first boot, because a container that is still migrating will be reported unhealthy rather than failed.

A commented redis service using the valkey/valkey image appears in the file under the label Optional for HA Setup. The .env.sample explains the consequence: Redis is used for Pub/Sub for WebSockets, and the application falls back to in-memory operation when it is absent. For a single instance, the fallback is fine. For more than one replica, in-memory pub/sub means a message published on one process does not reach clients connected to another, so the commented block is the thing to uncomment if you scale horizontally.

The environment file is the other half of the architecture. .env.sample documents KANEO_CLIENT_URL, an optional KANEO_API_URL that defaults to KANEO_CLIENT_URL/api, an optional KANEO_INTERNAL_API_URL used for internal MCP tool requests, and CORS_ORIGINS which defaults to KANEO_CLIENT_URL. The sample also warns that leaving AUTH_SECRET unset causes a random secret to be generated at startup, which means sessions will not survive restarts.

Installing Kaneo with Docker Compose and opening it for the first time

The README gives a single-container Compose file as the fastest way to try Kaneo. The repository's own compose.yml is slightly larger, adding a healthcheck to the kaneo service and a commented Redis block, so either version works. Save the file as compose.yml in an empty directory.

services:
  postgres:
    image: postgres:16-alpine
    env_file:
      - .env
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U kaneo -d kaneo"]
      interval: 10s
      timeout: 5s
      retries: 5

  kaneo:
    image: ghcr.io/usekaneo/kaneo:latest
    ports:
      - "5173:5173"
    env_file:
      - .env
    depends_on:
      postgres:
        condition: service_healthy
    restart: unless-stopped

volumes:
  postgres_data:

Next, copy .env.sample to .env. The README's instructions for the quick start are specific: uncomment KANEO_CLIENT_URL=http://localhost:5173, set POSTGRES_PASSWORD to a password, and set AUTH_SECRET to the output of the command below. Leaving AUTH_SECRET empty is allowed, but the sample file states that a random secret is generated at startup and sessions will not survive restarts.

openssl rand -hex 32

With the environment file in place, start the stack and confirm both containers report healthy. The kaneo healthcheck polls /api/health, so a healthy status is the signal that the web process is answering, not just that the container started.

docker compose up -d
docker compose ps

Open http://localhost:5173 in a browser. The README notes that inside Compose the Kaneo container reaches PostgreSQL at the service hostname postgres, and that if you run the API on your host instead of in Compose you should use localhost or set DATABASE_URL explicitly. Getting that wrong is the most likely cause of a first-run connection error.

The MCP endpoint is the feature that separates Kaneo from a plain kanban board

Kaneo ships an official MCP server, which the README describes as letting AI tools such as Claude and Cursor manage tasks, projects, and labels. Two access paths exist. Every instance exposes a built-in HTTP MCP endpoint at /api/mcp, so self-hosted users get it without installing anything extra. For stdio clients, there is a published package, @kaneo/mcp on npm, runnable with npx -y @kaneo/mcp.

The .env.sample adds a detail that matters in real deployments: KANEO_INTERNAL_API_URL is described as being for internal MCP tool requests only, and it defaults to http://127.0.0.1:1337. That implies the MCP layer talks to the API over a loopback address rather than through the public URL, which is why the Coolify instructions tell you to leave KANEO_API_URL unset and warn that a localhost value breaks browser API calls. The two variables serve different callers and should not be conflated.

If you do not care about AI clients, this section is irrelevant to you, and that is fine. But it is the one capability in the README that a comparable self-hosted tracker is unlikely to match out of the box, and it costs you nothing to leave switched off.

Where Kaneo is the wrong tool

The first limitation is operational. Kaneo is not a hosted service in its default form. You need a machine, a PostgreSQL 16 instance, a domain if you want HTTPS, and someone who will notice when the container stops. The drim CLI automates much of this, and the README says it handles automatic HTTPS and database setup, but that is still a server you own.

The second is the feature set. The README's own argument is that fewer features are better, which means features you may already depend on elsewhere are simply not part of the pitch. If your team needs documented time tracking, portfolio-level reporting, or a large integration marketplace, the README does not claim any of that, and you should not assume it exists.

The third is a documentation gap around failure. The README documents how to start the stack and how to configure it, but it does not describe a rollback procedure, a migration downgrade path, or what happens to the postgres_data volume across image upgrades. Since the Compose file pins ghcr.io/usekaneo/kaneo:latest rather than a version tag, a restart can pull a newer image than the one your database was migrated for. Pinning a specific tag is the obvious mitigation, and the README does not suggest it.

Finally, the search interest around this name is heavily diluted. People searching for Kaneo are often looking for a place in Hawaii or a boat, not a project management tool. That is not a product flaw, but it does mean community answers are harder to find by search than the project's activity level would suggest.

Alternatives, and the real difference in approach

The closest comparison in this space is Plane, another open source project management tool. Both are self-hosted, both target engineering teams, and both offer Docker-based deployment. The difference is scope: Plane positions itself as a broader work management platform with cycles, modules, and multiple views, while Kaneo's README explicitly argues that having too many features is the problem. If your team wants a tool that can absorb every process you might adopt later, Kaneo's restraint works against you.

A second comparison is Vikunja, which is also self-hosted and open source but is written in Go, so it ships as a single binary with a smaller runtime footprint than a Node and PostgreSQL stack. Kaneo's package.json requires Node 24 or newer and pnpm 10.32.1 for development, and the production image runs the web app on port 5173 behind PostgreSQL. If minimising moving parts is your priority, a single-binary tool is easier to operate. If you want the MCP endpoint and a TypeScript codebase you can modify, that trade runs the other way.

A third option is simply a hosted SaaS tracker. The difference there is not features but responsibility: with a hosted tool you do not run PostgreSQL, do not manage backups of a named volume, and do not think about AUTH_SECRET rotation. Kaneo's answer is that your data stays yours, which is a real benefit only if you were going to do something with that control.

Maintenance, licence, and the cost of upgrading

The repository is not archived, and the last push was on 2026-08-21, with releases v2.20.0, v2.21.0, and v2.22.0 all published within the three days before that. That is a fast release cadence, and the repository contains semantic-release configuration plus a conventional commits setup, so version bumps are automated from commit messages. For an operator, a fast cadence is a mixed signal: fixes arrive quickly, and so do changes you did not ask for.

The practical upgrade cost sits in the database. The Compose file mounts a named volume postgres_data, and the README does not document a downgrade path or a migration rollback. That means the safe operating habit is to back up the volume before pulling a new image, and to pin the image tag instead of using latest. Neither step is described in the README, so treat them as your responsibility.

The licence is MIT, which is permissive: it allows commercial use, modification, and redistribution, and it requires that the licence text be preserved. The README asks for sponsorship but does not tie any licence term to it. This is a description of the licence identifier, not legal advice; if you redistribute Kaneo inside a product, have your own counsel read the LICENSE file.

Editorial conclusion

Adopt Kaneo if you want a small, self-hosted task tracker you control and you are comfortable running PostgreSQL alongside it, or if you specifically want an MCP endpoint that AI clients can call without extra plumbing. Do not adopt it if you need a hosted SaaS with no operational work, or if you depend on a documented rollback path, since the README does not describe one. Before committing, verify that the Docker Compose stack comes up healthy on your host, that AUTH_SECRET is set to a fixed value so sessions survive restarts, and that POSTGRES_PASSWORD is not left blank.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes