Yokan Board MCP

🚀 Yokan Board MCP

本项目是一个面向 Yokan 看板 API 的模型上下文协议（MCP）服务器。它为 AI 代理提供了一个基于工具的接口，用于与看板、列和任务进行交互和管理。

✨ 主要特性

• 看板管理：创建、检索、更新和删除看板。
• 列管理：在看板内创建、检索、更新、重新排序和删除列。
• 任务管理：创建、检索、更新、移动和删除任务。
• 支持代理：设计用于 AI 代理通过主控制协议使用。

🛠️ 技术栈

• Python
• FastAPI
• Pydantic
• fastmcp

🚀 快速开始

构建并运行 Docker 镜像

对于新用户或不想设置开发环境就运行服务器的用户，我们建议使用 Docker。

1. 构建 Docker 镜像：

docker build -t yokanboard/yokan-mcp .

2. 运行 Docker 容器：

docker run -p 8888:8888 --name yokan-mcp -e YOKAN_API_BASE_URL=http://your-yokan-api-host:port/api yokanboard/yokan-mcp

请确保将 http://your-yokan-api-host:port/api 替换为你实际的 Yokan API 实例的 URL。

MCP 客户端配置

使用可流式传输的 Gemini CLI

创建 .gemini/settings.json 文件，内容如下：

{
    "mcpServers": {
        "yokan-board": {
            "httpUrl": "http://[your-yokan-mcp-host]:8888/mcp",
            "headers": {
                "Authorization": "Bearer [TOKEN]",
                "accept": "application/json"
            }
        }
    }
}

使用标准输入输出传输的 VS Code Copilot

创建 .vscode/mcp.json 文件，内容如下：

{
    "servers": {
        "yokan-board": {
            "type": "stdio",
            "command": "uv",
            "args": [
                "run",
                "--directory",
                "/full/path/to/yokan-board-mcp-project-folder/yokan-board-mcp",
                "-m",
                "src.main",
                "--stdio"
            ]
        }
    }
}

🛠️ 开发

前提条件

• Python 3.8+
• uv（用于管理 Python 环境）
• 能够访问正在运行的 Yokan API 实例。

环境搭建

1. 克隆仓库：

git clone https://github.com/yokan-board/yokan-board-mcp.git
cd yokan-board-mcp

2. 创建并激活虚拟环境：

uv venv
source .venv/bin/activate

3. 安装依赖：

uv sync

配置

1. 通过复制 .env.example 文件创建 .env 文件：

cp .env.example .env

2. 编辑 .env 文件，指向你的 Yokan API 实例：

YOKAN_API_BASE_URL=http://your-yokan-api-host:port/api

运行服务器

要启动用于开发的 MCP 服务器，请运行以下命令：

uvicorn src.main:app --host localhost --port 8888 --reload

🧪 测试

要运行集成测试，你需要有一个正在运行的 Yokan API 实例和一个测试用户。测试配置为使用用户名 user 和密码 password。 确保你的 .env 文件已正确配置 YOKAN_API_BASE_URL。 使用以下命令运行测试：

make test

🛠️ 可用工具

MCP 服务器提供了以下用于管理 Yokan 看板的工具：

💻 使用示例

你可以使用 fastmcp 客户端库与 MCP 服务器进行交互。

身份验证

要使用这些工具，你首先需要从你的 Yokan API 实例获取 JWT 令牌。你可以通过向 Yokan API 的 /login 端点发送 POST 请求来实现。 使用 curl 的示例：

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"username": "your_username", "password": "your_password"}' \
  http://localhost:3001/api/v1.1/login

示例：与 MCP 服务器交互

一个展示如何使用 fastmcp 客户端与 Yokan MCP 服务器进行交互的 Python 示例可以在 中找到。

📄 版权信息

Yokan Board MCP 由 Julian I. Kamil 创建。 © 版权所有 2025 Julian I. Kamil。保留所有权利。

📄 许可证

Yokan Board MCP 采用双重许可：

• AGPLv3：根据 GNU Affero 通用公共许可证第 3 版的条款免费使用、修改和分发（请参阅 LICENSE.AGPLv3）。
• 商业许可证：适用于希望在不遵循 AGPLv3 版权共享要求的情况下使用 Yokan 的组织（请参阅 LICENSE.COMMERCIAL）。 如需商业使用许可信息，请发送电子邮件至：yokan.board@gmail.com