AI导哈

Planka MCP服务

一个轻量级的MCP服务器，通过Planka REST API连接AI聊天客户端与Planka看板，实现数据读写操作。

  • by roelven
  • Python
  • 本地部署
  • 3 星标
  • 更新于
在 GitHub 查看 roelven/another-planka-mcp

使用说明

另一个Planka MCP

模型上下文协议（MCP）服务器，使AI聊天客户端能够使用Planka REST API读取和更新您的Planka板。

概述

另一个Planka MCP服务器为您提供了MCP客户端和自托管Planka实例之间的轻量级桥梁。它通过MCP工具公开项目、板、列表、卡、任务和标签，允许助手检索工作区数据并执行写操作，如创建或更新卡。

特性

  • 列出项目、板、列表、标签和成员。
  • 搜索和检索具有多个详细级别的卡片。
  • 创建和更新卡片（标题、描述、标签、任务）。
  • 在列表之间移动卡片。
  • 通过结构化MCP工具高效使用代币。
  • 适用于Claude Desktop、Claude.ai和任何兼容MCP的客户端。
  • 通过流式http传输和Docker部署进行远程访问。

示例用例：

  • “在我的工作区中显示所有“进行中”卡。”
  • “在中创建新卡 <Board> / 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用户权限相匹配
  • 管理员用户具有完全访问权限；普通用户只能访问他们所属的董事会

设置

  1. 克隆仓库：

    git clone https://github.com/roelven/another-planka-mcp
cd another-planka-mcp

  2. 创建环境：

    python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

  3. 复制env文件：

    cp .env.example .env

  4. 填写：

    • PLANKA_BASE_URL
    • PLANKA_API_TOKEN （推荐）

  5. 启动服务器：

    python mcp_server.py

  6. 添加到Claude桌面配置：

    {
  "mcpServers": {
    "planka": {
      "command": "/absolute/path/to/venv/bin/python",
      "args": ["mcp_server.py"],
      "env": {
        "PLANKA_BASE_URL": "https://your.domain",
        "PLANKA_API_TOKEN": "<token>"
      }
    }
  }
}

远程部署（Docker）

为了使MCP服务器远程可用（例如用于Claude.ai），您可以使用可流化的http传输使用Docker进行部署。

  1. 在服务器上克隆仓库：
    git clone https://github.com/roelven/another-planka-mcp
cd another-planka-mcp
  2. 创建一个 .env 使用您的Planka凭据进行归档：
    cp .env.example .env
# Edit .env with PLANKA_BASE_URL and PLANKA_API_TOKEN
  3. 启动容器：
    docker compose up -d --build
  4. MCP服务器现在通过可流式传输的http在端口8000上运行。通过反向代理或Cloudflare隧道公开它，然后使用服务器的URL将其添加为Claude.ai中的远程MCP服务器。

这 MCP_TRANSPORT 环境变量控制运输方式：

  • stdio （默认）--用于本地MCP客户端，如Claude Desktop
  • streamable-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.

相关 MCP