内容
# Kanboard MCP 服务器
一款模型上下文协议（MCP）服务器，暴露 Kanboard API 功能给大型语言模型（LLMs），使 AI 助手能够与 Kanboard 项目管理系统交互。
## 功能特点
该 MCP 服务器提供对 60 多个 Kanboard API 端点的访问，这些端点被组织成以下类别：
- **项目** （5 个工具）：获取所有项目、按 ID/名称获取项目、项目活动
- **任务** （11 个工具）：创建、读取、更新、删除任务；搜索任务；处理逾期任务
- **分类** （2 个工具）：获取项目的分类
- **栏目** （2 个工具）：获取看板栏目信息
- **看板** （1 个工具）：获取看板信息
- **评论** （5 个工具）：创建、读取、更新、删除任务评论
- **用户** （9 个工具）：获取用户信息、当前用户信息、仪表盘、项目
- **链接** （12 个工具）：创建和管理任务链接及链接类型
- **子任务** （5 个工具）：创建、读取、更新、删除子任务
- **标签** （4 个工具）：管理任务标签
- **文件** （6 个工具）：上传、下载和管理任务文件附件
## 安装
### 前提条件
- Python 3.10 或更高版本
- 可访问且启用 API 的 Kanboard 实例
- Kanboard API 令牌
### 从 PyPI 安装（推荐）
```bash
# 使用 uvx 安装（无需管理 Python 环境）
uvx kanboard-mcp
# 或使用 pip 安装
pip install kanboard-mcp
```
### 从源码安装
```bash
# 克隆仓库
git clone https://github.com/hoducha/kanboard-mcp.git
cd kanboard-mcp
# 使用 uv 安装
uv sync
# 或使用 pip 安装
pip install -e .
```
### 开发环境安装
```bash
# 使用 uv
uv sync --all-extras
# 或使用 pip
pip install -e ".[dev]"
```
## 配置
### 环境变量
在项目根目录创建 `.env` 文件，包含以下变量：
```env
# 必需
KANBOARD_URL=https://your-kanboard.com/jsonrpc.php
KANBOARD_API_TOKEN=your_api_token_here
# 可选
KANBOARD_USERNAME=jsonrpc
KANBOARD_VERIFY_SSL=true
KANBOARD_TIMEOUT=30
KANBOARD_MAX_RETRIES=3
KANBOARD_RETRY_DELAY=1.0
# MCP 服务器设置
MCP_SERVER_NAME="Kanboard MCP 服务器"
MCP_SERVER_VERSION="0.1.0"
DEBUG=false
```
### 获取 API 令牌
1. 登录到您的 Kanboard 实例
2. 进入 **设置** → **API**
3. 生成新的 API 令牌
4. 复制令牌并作为 `KANBOARD_API_TOKEN`
## 使用
### 运行服务器
```bash
# 使用 uvx（推荐 - 无需安装）
uvx kanboard-mcp
# 或使用已安装的命令
kanboard-mcp
# 或使用 Python 模块
python -m kanboard_mcp.server
```
### MCP 客户端集成
将服务器添加到您的 MCP 客户端配置中。对于 Claude Desktop，请在 `claude_desktop_config.json` 中添加：
**选项 1：使用 uvx（推荐）**
```json
{
"mcpServers": {
"kanboard": {
"command": "/Users/username/.local/bin/uvx",
"args": ["kanboard-mcp"],
"env": {
"KANBOARD_URL": "https://your-kanboard.com/jsonrpc.php",
"KANBOARD_API_TOKEN": "your_api_token_here"
}
}
}
}
```
**注意**：将 `/Users/username/.local/bin/uvx` 替换为您的实际 uvx 路径。可以在终端中运行 `which uvx` 找到它。
**选项 2：使用已安装的软件包**
```json
{
"mcpServers": {
"kanboard": {
"command": "kanboard-mcp",
"env": {
"KANBOARD_URL": "https://your-kanboard.com/jsonrpc.php",
"KANBOARD_API_TOKEN": "your_api_token_here"
}
}
}
}
```
### 测试连接
服务器提供内置工具用于测试：
- `test_connection`: 测试与 Kanboard 的连接
- `get_server_info`: 获取服务器信息和功能
- `get_config_info`: 获取当前配置（不含敏感数据）
## API 工具
### 项目
- `getAllProjects()`: 获取所有项目
- `getProjectById(project_id)`: 按 ID 获取项目
- `getProjectByName(project_name)`: 按名称获取项目
- `getProjectActivity(project_id)`: 获取项目活动
- `getProjectActivities(project_id)`: 获取项目活动
### 任务
- `getAllTasks(project_id, status_id?)`: 获取项目的所有任务
- `getTask(task_id)`: 获取特定任务
- `getTaskByReference(project_id, reference)`: 按引用获取任务
- `getOverdueTasks()`: 获取所有逾期任务
- `getOverdueTasksByProject(project_id)`: 获取项目的逾期任务
- `createTask(project_id, title, ...)`: 创建新任务
- `updateTask(task_id, ...)`: 更新现有任务
- `openTask(task_id)`: 打开任务
- `closeTask(task_id)`: 关闭任务
- `removeTask(task_id)`: 删除任务
- `searchTasks(project_id, query, ...)`: 搜索任务
### 评论
- `createComment(task_id, content, user_id?)`: 创建评论
- `getComment(comment_id)`: 获取评论
- `getAllComments(task_id)`: 获取任务的所有评论
- `updateComment(comment_id, content)`: 更新评论
- `removeComment(comment_id)`: 删除评论
### 还有更多...
请参阅 `src/kanboard_mcp/tools/` 中的各个工具模块以获取完整的 API 文档。
## 错误处理
所有工具返回以下格式的响应：
```json
{
"success": true,
"data": { ... }
}
```
或在出错时：
```json
{
"success": false,
"error": "错误信息"
}
```
## 开发
### 项目结构
```
kanboard-mcp/
├── src/kanboard_mcp/
│ ├── __init__.py
│ ├── server.py # 主 MCP 服务器
│ ├── config.py # 配置管理
│ ├── client.py # Kanboard 客户端包装器
│ └── tools/ # API 工具实现
│ ├── projects.py
│ ├── tasks.py
│ ├── categories.py
│ ├── columns.py
│ ├── boards.py
│ ├── comments.py
│ ├── users.py
│ ├── links.py
│ ├── subtasks.py
│ ├── tags.py
│ └── files.py
├── pyproject.toml
└── README.md
```
### 运行测试
```bash
pytest
```
### 代码质量
```bash
# 格式化代码
black src/
# 排序导入
isort src/
# 类型检查
mypy src/
# linting
ruff src/
```
## 故障排除
### 常见问题
1. **连接错误**：检查您的 `KANBOARD_URL` 并确保 API 端点正确
2. **身份验证错误**：验证您的 `KANBOARD_API_TOKEN` 是否有效
3. **SSL 错误**：对于自签名证书，设置 `KANBOARD_VERIFY_SSL=false`（不建议在生产环境中使用）
4. **超时问题**：增加 `KANBOARD_TIMEOUT` 值
### Claude Desktop 问题
**找不到 Python 命令（`spawn python ENOENT`）**
如果出现此错误，Claude Desktop 无法找到 Python 可执行文件。以下是解决方法的优先级：
1. **使用 uvx（推荐）**：
```json
{
"mcpServers": {
"kanboard": {
"command": "/Users/username/.local/bin/uvx",
"args": ["kanboard-mcp"],
"env": { ... }
}
}
}
```
2. **使用 pip 安装的软件包**：
```json
{
"mcpServers": {
"kanboard": {
"command": "kanboard-mcp",
"env": { ... }
}
}
}
```
3. **使用完整的 Python 路径**：
```json
{
"mcpServers": {
"kanboard": {
"command": "/usr/local/bin/python3",
"args": ["-m", "kanboard_mcp.server"],
"env": {
"PYTHONPATH": "/path/to/site-packages",
...
}
}
}
}
```
**uvx 的优势**：
- 无需管理 Python 环境
- 自动安装和运行最新版本
- 跨不同 Python 安装有效
- 最简单的配置
### 调试模式
启用调试模式以获取详细日志：
```bash
DEBUG=true kanboard-mcp
```
## 贡献
1. 分叉仓库
2. 创建功能分支
3. 进行更改
4. 添加测试
5. 运行代码质量检查
6. 提交拉取请求
## 许可证
MIT 许可证 - 请参阅 LICENSE 文件获取详细信息。
## 支持
如有问题和疑问：
- 检查故障排除部分
- 查看 Kanboard API 文档：https://docs.kanboard.org/v1/api/
- 在 GitHub 上打开问题
