# Kan

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

Kan 使用 AGPLv3 协议发布。

- [项目主页](https://kan.bn)
- [在线文档](https://docs.kan.bn)
- [路线图](https://kan.bn/kan/roadmap)
- [Discord 社区](https://discord.gg/e6ejRb6CmT)

![Kan 截图](https://github.com/user-attachments/assets/8490104a-cd5d-49de-afc2-152fd8a93119)

## 功能

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

## 使用 Docker Compose 自托管

### 环境要求

- Docker Engine
- Docker Compose v2

### 启动

在仓库根目录执行：

```bash
cp .env.example .env
```

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

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

构建本地镜像并启动：

```bash
docker compose up -d --build
```

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

```yaml
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`。

### 常用命令

```bash
# 查看状态
docker compose ps

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

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

# 停止服务
docker compose down

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

检查 API 健康状态：

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

预期返回：

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

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

## 本地开发

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

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

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

```bash
pnpm typecheck
pnpm lint
pnpm format
```

## 环境变量

完整变量列表见 [`.env.example`](.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 公共包。因此以下命令不能使用：

```bash
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`。

### 构建

在仓库根目录执行：

```bash
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 时：

```text
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` 中的路径替换为本机仓库的绝对路径：

```json
{
  "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 路径示例：

```json
{
  "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`：

```json
{
  "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 服务。将脚本路径替换为本机绝对路径：

```bash
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：

```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：

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

PowerShell：

```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](CONTRIBUTING.md)，并运行类型检查、Lint 和格式检查。

## 许可证与联系

项目使用 [AGPLv3](LICENSE) 协议。如需支持，请发送邮件至 [henry@kan.bn](mailto:henry@kan.bn)，或加入 [Discord 社区](https://discord.gg/e6ejRb6CmT)。