Kan

Kan 是一个开源的看板式项目管理工具，可作为 Trello 的自托管替代方案。它支持工作区、看板、列表、卡片、标签、成员、评论、检查清单和活动记录。

Kan 使用 AGPLv3 协议发布。

• 项目主页
• 在线文档
• 路线图
• Discord 社区

功能

• 看板可见性控制
• 工作区成员和协作
• Trello 看板导入
• 卡片标签和筛选
• 评论、活动记录和检查清单
• 可复用的看板模板
• 卡片截止日期、成员和附件
• 内置 REST API 和 MCP 服务

使用 Docker Compose 自托管

环境要求

• Docker Engine
• Docker Compose v2

启动

在仓库根目录执行：

cp .env.example .env

编辑 .env，至少设置以下变量：

NEXT_PUBLIC_BASE_URL=http://localhost:3000
POSTGRES_PASSWORD=请填写数据库密码
POSTGRES_URL=postgresql://kan:请填写数据库密码@postgres:5432/kan_db
BETTER_AUTH_SECRET=请填写一个随机的 32 位以上密钥

构建本地镜像并启动：

docker compose up -d --build

仓库自带的 docker-compose.yml 使用本地镜像标签：

services:
  migrate:
    image: kan-migrate:local
    build:
      context: .
      dockerfile: ./apps/web/Dockerfile
      target: migrate
  web:
    image: kan:local
    build:
      context: .
      dockerfile: ./apps/web/Dockerfile
      target: web

不会拉取远端 Web 镜像。数据库迁移会在 Web 服务启动前自动执行。启动完成后访问 http://localhost:3000。如修改端口，请同步修改 WEB_PORT 和 NEXT_PUBLIC_BASE_URL。

常用命令

# 查看状态
docker compose ps

# 查看 Web 日志
docker compose logs -f web

# 查看迁移日志
docker compose logs -f migrate

# 停止服务
docker compose down

# 停止服务并删除数据库卷（会删除本地数据）
docker compose down -v

检查 API 健康状态：

curl http://localhost:3000/api/v1/health

预期返回：

{ "status": "ok", "database": "ok", "storage": "not_configured" }

默认文件存储状态为 not_configured。如需上传头像和附件，请按照 .env.example 配置 S3 兼容存储。

本地开发

项目是 pnpm monorepo，需要 Node.js 20.18.1 或更高版本，以及 pnpm 9.14.2。

git clone https://github.com/kanbn/kan.git
cd kan
pnpm install
cp .env.example .env
pnpm db:migrate
pnpm dev

开发服务器默认地址为 http://localhost:3000。常用检查命令：

pnpm typecheck
pnpm lint
pnpm format

环境变量

完整变量列表见 .env.example。

变量	用途	示例
NEXT_PUBLIC_BASE_URL	当前 Kan 实例的访问地址	http://localhost:3000
POSTGRES_URL	PostgreSQL 连接地址	postgresql://kan:密码@postgres:5432/kan_db
POSTGRES_PASSWORD	Compose 创建 PostgreSQL 使用的密码	change-me
BETTER_AUTH_SECRET	登录会话加密密钥	随机 32 位以上字符串
WEB_PORT	宿主机映射端口	3000
REDIS_URL	可选的限流 Redis 地址	redis://redis:6379
NEXT_PUBLIC_ALLOW_CREDENTIALS	是否允许账号密码登录	true
NEXT_PUBLIC_DISABLE_SIGN_UP	是否关闭注册	false
KAN_ADMIN_API_KEY	管理和监控接口密钥	自定义密钥

MCP 服务

Kan 仓库内置了基于 Model Context Protocol 的 MCP 服务。连接后，Claude Desktop、Cursor、VS Code、Codex 等 MCP 客户端可以通过自然语言读取和管理 Kan 数据。

先看这里

MCP 源码位于 packages/mcp，目前是仓库内的工作区包，并未发布为 npm 公共包。因此以下命令不能使用：

npx -y @kan/mcp
bunx kan-mcp

请从当前仓库构建 MCP 服务，再让客户端启动生成的文件。

获取 API 密钥

1. 登录 Kan。
2. 打开设置中的 API 密钥页面，地址通常为 /settings/api。
3. 创建一个 API 密钥并立即保存。密钥只会完整显示一次。

MCP 使用用户 API 密钥，不是 KAN_ADMIN_API_KEY。请求会以 Bearer Token 方式访问 ${KAN_BASE_URL}/api/v1。

构建

在仓库根目录执行：

pnpm install
pnpm --filter @kan/mcp build

构建产物为 packages/mcp/dist/index.js。MCP 服务使用 stdio 通信，应由 MCP 客户端启动，不需要单独暴露 HTTP 端口。

环境变量

变量	说明
KAN_BASE_URL	Kan 实例根地址，不要追加 /api/v1
KAN_API_TOKEN	Kan 设置中创建的用户 API 密钥

本地 Kan 使用 Docker Compose 时：

KAN_BASE_URL=http://localhost:3000
KAN_API_TOKEN=kan_你的_api_key

Claude Desktop 和 Cursor

Claude Desktop 使用 claude_desktop_config.json，Cursor 使用项目内的 .cursor/mcp.json。将 args 中的路径替换为本机仓库的绝对路径：

{
  "mcpServers": {
    "kan": {
      "command": "node",
      "args": ["/绝对路径/kan/packages/mcp/dist/index.js"],
      "env": {
        "KAN_BASE_URL": "http://localhost:3000",
        "KAN_API_TOKEN": "kan_你的_api_key"
      }
    }
  }
}

Windows 路径示例：

{
  "mcpServers": {
    "kan": {
      "command": "node",
      "args": ["C:\\workspace\\kan\\packages\\mcp\\dist\\index.js"],
      "env": {
        "KAN_BASE_URL": "http://localhost:3000",
        "KAN_API_TOKEN": "kan_你的_api_key"
      }
    }
  }
}

VS Code 的 mcp.json 使用 servers 作为顶层键，并增加 type：

{
  "servers": {
    "kan": {
      "type": "stdio",
      "command": "node",
      "args": ["/绝对路径/kan/packages/mcp/dist/index.js"],
      "env": {
        "KAN_BASE_URL": "http://localhost:3000",
        "KAN_API_TOKEN": "kan_你的_api_key"
      }
    }
  }
}

Codex

Codex 可通过命令添加 stdio MCP 服务。将脚本路径替换为本机绝对路径：

codex mcp add kan \
  --env KAN_BASE_URL=http://localhost:3000 \
  --env KAN_API_TOKEN=kan_你的_api_key \
  -- node /绝对路径/kan/packages/mcp/dist/index.js

Windows PowerShell：

codex mcp add kan `
  --env KAN_BASE_URL=http://localhost:3000 `
  --env KAN_API_TOKEN=kan_你的_api_key `
  -- node C:\workspace\kan\packages\mcp\dist\index.js

使用 codex mcp get kan 检查配置。

手动启动和排错

Linux 或 macOS：

KAN_BASE_URL=http://localhost:3000 \
KAN_API_TOKEN=kan_你的_api_key \
node packages/mcp/dist/index.js

PowerShell：

$env:KAN_BASE_URL = "http://localhost:3000"
$env:KAN_API_TOKEN = "kan_你的_api_key"
node .\packages\mcp\dist\index.js

如果出现 Connection closed，检查以下内容：

1. 已执行 pnpm --filter @kan/mcp build。
2. args 指向真实存在的 packages/mcp/dist/index.js。
3. KAN_BASE_URL 只填写实例根地址。
4. KAN_API_TOKEN 是 Kan 用户 API 密钥。
5. http://localhost:3000/api/v1/health 返回数据库正常。

工具范围

当前 MCP 服务提供 46 个工具，覆盖工作区、看板、列表、卡片、评论、标签、检查清单和成员管理。连接后可以直接提出以下请求：

• 列出我的工作区。
• 查看研发工作区中的所有看板。
• 创建一个包含待办、进行中、已完成列表的新看板。
• 将登录问题卡片移动到进行中列表。
• 给版本发布卡片添加检查清单和评论。

技术栈

Next.js、React、tRPC、Better Auth、Tailwind CSS、Drizzle ORM、PostgreSQL 和 Model Context Protocol SDK。

参与贡献

欢迎提交 Issue 和 Pull Request。提交代码前请先阅读 CONTRIBUTING.md，并运行类型检查、Lint 和格式检查。

许可证与联系

项目使用 AGPLv3 协议。如需支持，请发送邮件至 henry@kan.bn，或加入 Discord 社区。