另一个Planka MCP
模型上下文协议（MCP）服务器，使AI聊天客户端能够使用Planka REST API读取和更新您的Planka板。
概述
另一个Planka MCP服务器为您提供了MCP客户端和自托管Planka实例之间的轻量级桥梁。它通过MCP工具公开项目、板、列表、卡、任务和标签，允许助手检索工作区数据并执行写操作，如创建或更新卡。
特性
- 列出项目、板、列表、标签和成员。
- 搜索和检索具有多个详细级别的卡片。
- 创建和更新卡片（标题、描述、标签、任务）。
- 在列表之间移动卡片。
- 通过结构化MCP工具高效使用代币。
- 适用于Claude Desktop、Claude.ai和任何兼容MCP的客户端。
- 通过流式http传输和Docker部署进行远程访问。
示例用例：
- “在我的工作区中显示所有“进行中”卡。”
- “在中创建新卡
/ TODO有子任务…” - “找到‘登录错误’卡并列出所有任务。”
先决条件
- Python 3.10+
- 访问Planka实例
- Planka API证书（见下文）
获取API证书
通过API验证生成JWT访问令牌：
curl -X POST https://your-planka-instance.com/api/access-tokens \
-H "Content-Type: application/json" \
-d '{
"emailOrUsername": "your-email@example.com",
"password": "your-password"
}'答复：
{
"item": {
"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
}复制 accessToken 重视并使用它 PLANKA_API_TOKEN 在你的 .env 文件。
备注：JWT令牌可能会过期。如果您遇到身份验证错误，请生成一个新令牌。
电子邮件/密码（回退）
直接使用您的Planka登录凭据。MCP服务器将在启动时自动进行身份验证：
PLANKA_EMAIL=your-email@example.com
PLANKA_PASSWORD=your-password用户需求：
- 任何注册的Planka用户都可以进行身份验证
- 无需特殊权限或管理员角色
- API访问权限与您的Planka用户权限相匹配
- 管理员用户具有完全访问权限；普通用户只能访问他们所属的董事会
设置
- 克隆仓库：
git clone https://github.com/roelven/another-planka-mcp
cd another-planka-mcp- 创建环境：
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt- 复制env文件：
cp .env.example .env- 填写：
- PLANKA_BASE_URL - PLANKA_API_TOKEN （推荐）
- 启动服务器：
python mcp_server.py- 添加到Claude桌面配置：
{
"mcpServers": {
"planka": {
"command": "/absolute/path/to/venv/bin/python",
"args": ["mcp_server.py"],
"env": {
"PLANKA_BASE_URL": "https://your.domain",
"PLANKA_API_TOKEN": ""
}
}
}
}远程部署（Docker）
为了使MCP服务器远程可用（例如用于Claude.ai），您可以使用可流化的http传输使用Docker进行部署。
- 在服务器上克隆仓库：
git clone https://github.com/roelven/another-planka-mcp
cd another-planka-mcp- 创建一个
.env使用您的Planka凭据进行归档：
cp .env.example .env
# Edit .env with PLANKA_BASE_URL and PLANKA_API_TOKEN- 启动容器：
docker compose up -d --build- MCP服务器现在通过可流式传输的http在端口8000上运行。通过反向代理或Cloudflare隧道公开它，然后使用服务器的URL将其添加为Claude.ai中的远程MCP服务器。
这 MCP_TRANSPORT 环境变量控制运输方式：
stdio（默认）--用于本地MCP客户端，如Claude Desktopstreamable-http--用于通过HTTP进行远程访问
工具和功能
| 工具 | 类型 | 用途 |
|---|---|---|
planka_get_workspace | 阅读 | 检索板、列表、用户、标签 |
planka_list_cards | 阅读 | 过滤并列出具有详细级别的卡片 |
planka_find_and_get_card | 阅读 | 搜索并获取特定卡片 |
planka_create_card | 写 | 创建新卡 |
planka_update_card | 写入 | 更新现有卡 |
使用示例
问你的助手：
- “列出我所有的板。”
- “搜索提及‘发票’的卡片。”
- “使用这些子任务创建名为“应用程序发布清单”的卡…”
- “将‘集成支付API’卡移动到‘完成’。”
安全和权限
- MCP服务器只访问经过身份验证的Planka用户可以访问的内容。
- 建议使用API令牌而不是电子邮件/密码。
- 在外部暴露Planka时使用HTTPS。
- 考虑使用具有受限权限的专用Planka服务用户。
故障排除和常见问题
401未经授权\ 检查令牌有效性和 .env 配置。
客户端无法连接到服务器\ 验证：
- 正确的Python路径
- 防火墙规则
- 执行权限
没有归还任何板或卡\ 确认Planka用户具有工作区访问权限。
开发说明
可编辑安装：此项目使用可编辑的安装（通过 pip install -e . 或虚拟环境中的等效物），这意味着 src 目录会自动添加到您的Python路径中。这消除了手动设置的需要 PYTHONPATH 在运行测试或服务器时。
设置可编辑模式：如果需要在可编辑模式下重新安装软件包，可以运行：
pip install -e .这创建了一个 .pth 虚拟环境中指向的文件 src 目录，使所有导入无缝工作。
运行测试
该项目包括一个代码覆盖率超过90%的全面测试套件。
由于该软件包是以可编辑模式安装的，因此您可以直接运行测试，而无需设置PYTHONPATH：
# Install test dependencies
pip install -r requirements.txt
# Run all tests
pytest --cov=src/planka_mcp --cov-report=term-missing
# Run specific test file
pytest tests/test_cards.py -v
# View coverage report
open htmlcov/index.html或者，您可以直接使用虚拟环境的pytest：
venv/bin/pytest --cov=src/planka_mcp --cov-report=term-missing使用MCP检查员进行测试
npx @modelcontextprotocol/inspector python mcp_server.py致谢
- Planka项目：https://github.com/plankanban/planka
- 模型上下文协议：https://modelcontextprotocol.io/
许可证
MIT许可证。看 LICENSE.