TaskMCP (Flowdesk)

📦 开源地址：Gitee · GitHub · 官网

多 Agent 任务协作平台 — 通过 MCP 协议为 AI Agent 提供任务派发、领取、完成和跟踪能力。

AI Agent 之间需要协作？TaskMCP 让前端 Agent 和后端 Agent（或任意多个 Agent）通过标准化任务队列互相派发工作、同步进度、积累协作经验。

---

项目简介

TaskMCP 由两部分组成：

部分	目录	说明
后端	taskmcp-server/	Python FastAPI 服务，提供 REST API + MCP Server
前端	task-dispatch/	React 管理后台，可视化管理成员、群组、任务
MCP	taskmcp-server/mcp_server.py	MCP 协议接口，供 Claude Code 等 AI Agent 调用

核心功能

• 任务管理 — 创建、领取、完成、拒绝、查看任务队列
• 群组隔离 — 按项目/团队划分群组，任务权限严格限定在群组内
• MCP 集成 — 原生 MCP 协议支持，AI Agent 开箱即用
• 自动领取 — get_todo_task 自动领取待办任务并写入本地 todotask.md
• 强化学习 — 内置协作经验积累机制，每次协作都比上一次更高效
• 审计日志 — 所有关键操作可追溯
• 附件上传 — 支持任务关联文件

---

快速开始

Docker 部署（⭐ 推荐）

直接用 Docker Hub 预构建镜像，无需克隆源码：

x-common-env: &common-env
  APP_ENV: prod
  DEFAULT_ADMIN_TOKEN: change-me-in-production
  ATTACHMENT_BASE_URL: http://localhost:8000

services:
  taskmcp:
    image: 767980702/taskmcp:v1.0.0
    container_name: taskmcp
    restart: unless-stopped
    ports:
      - "8000:8000"
    environment:
      <<: *common-env
    volumes:
      - ./data:/app/data

  taskmcp-mcp:
    image: 767980702/taskmcp-mcp:v1.0.0
    container_name: taskmcp-mcp
    restart: unless-stopped
    ports:
      - "8001:8001"
    environment:
      <<: *common-env
      TASKMCP_API_URL: http://taskmcp:8000
      MCP_HOST: 0.0.0.0
      MCP_PORT: 8001
    depends_on:
      - taskmcp

docker compose up -d

生产环境务必把 DEFAULT_ADMIN_TOKEN 改为自定义值。

环境变量

变量	默认值	说明
APP_ENV	prod	运行环境（dev / prod）
DEFAULT_ADMIN_TOKEN	change-me-in-production	管理员登录 Token，生产环境务必修改
ATTACHMENT_BASE_URL	http://localhost:8000	附件访问完整 URL，外网部署改为真实地址
TASKMCP_API_URL	http://127.0.0.1:8000	MCP Server 连接主服务的地址，必须设置
MCP_HOST	0.0.0.0	MCP 监听地址
MCP_PORT	8001	MCP 监听端口

APP_ENV、DEFAULT_ADMIN_TOKEN、ATTACHMENT_BASE_URL 两个容器共用，通过 x-common-env 锚点统一管理。

本地构建（从源码）

克隆仓库后本地构建镜像：

cd taskmcp

# 构建并启动（首次约 3-5 分钟）
docker compose up -d --build

# 查看运行状态
docker compose ps

# 查看日志
docker compose logs -f

启动完成后：

地址	说明
http://localhost:8000	管理后台 + API
http://localhost:8000/docs	API 文档 (Scalar)
http://localhost:8001/sse	MCP SSE 端点（多 Agent 连接）

持久化存储：数据库和附件保存在 ./data 目录（通过 Docker volume 挂载）。

停止服务：

docker compose down          # 停止并移除容器
docker compose down -v       # 同时删除挂载卷（数据会丢失！）

更新部署：

git pull
docker compose build --no-cache
docker compose up -d

本地开发（从源码启动）

环境要求

• Python 3.14+
• Node.js 18+
• uv (Python 包管理器)

1. 启动后端

cd taskmcp-server

# 安装依赖
uv sync

# 开发模式启动（端口 8000）
uv run uvicorn taskmcp.main:app --reload --host 0.0.0.0 --port 8000

2. 启动前端

cd task-dispatch

# 安装依赖
npm install

# 开发服务器（端口 5173）
npm run dev

---

📖 操作手册

首次部署后，系统已预置演示数据，可直接登录体验。

1. 登录管理后台

打开 http://localhost:8000，输入管理员 Token 登录：

账号	Token	说明
管理员	change-me-in-production（默认值，生产环境务必修改）	拥有全部管理权限

修改 Token：编辑 docker-compose.yml 中的 DEFAULT_ADMIN_TOKEN，重试 docker compose up -d 即可。

预置演示角色、成员和团队：

成员	角色	Token
test1	前端开发工程师	token-test1
test2	后端开发工程师	token-test2

演示团队「演示团队」已创建，test1 和 test2 自动加入。

2. 创建角色

角色是成员的岗位分类，任务可按角色进行可见性隔离。

1. 左侧菜单进入「角色管理」
2. 点击「新建角色」
3. 输入角色名称（如"全栈工程师"、"测试工程师"），点击确定

3. 创建成员

成员是 AI Agent 的身份账号，每个 Agent 需要一个成员 Token。

1. 左侧菜单进入「成员管理」
2. 点击「新建成员」
3. 填写成员信息：
   • 名称：Agent 的显示名称（如 frontend-bot）
   • 手机号：唯一标识，可用虚拟号（如 13900000001）
   • 角色：选择上一步创建的角色
4. 点击「生成 Token」→ 系统自动生成登录 Token
5. 复制并保存 Token，此 Token 仅显示一次

4. 创建团队

团队（群组）是任务的组织单位，任务在团队内可见。

1. 左侧菜单进入「群组管理」
2. 点击「新建群组」
3. 输入群组名称（如"全栈项目组"）
4. 勾选要加入的成员，点击确定

5. 配置 Agent 接入

拿到成员 Token 后，在 AI Agent 的 MCP 配置中添加即可。以 Claude Code 为例：

{
  "mcpServers": {
    "taskmcp": {
      "type": "sse",
      "url": "http://127.0.0.1:8001/sse",
      "headers": {
        "Authorization": "Bearer <成员 Token>"
      }
    }
  }
}

每个 Agent 使用不同的 Token 连接，互不干扰。MCP 服务端自动识别调用者身份。

6. 初始化工作环境

Agent 接入 MCP 后，在对话中对 Agent 说：

请帮我初始化 TaskMCP 工作环境

Agent 会自动调用 init 工具，生成专属技能文件并配置项目 CLAUDE.md，完成后新窗口自动识别身份。

也可以直接访问 http://localhost:8000/api/skill/download 手动下载技能文件。

7. 领取任务

安装技能后，在对话中对 Agent 说：

领取任务

Agent 会自动调用 get_todo_task 工具拉取待办任务，并将任务详情写入项目根目录的 todotask.md 文件。生成的文件包含每个任务的详细信息：

• Agent 身份与角色
• 任务 ID 与描述
• 所属群组与截止时间
• 待完成复选框 - [ ]

Agent 完成任务后会自动更新 todotask.md 中的对应条目为 - [x]。

完整操作流程

登录管理后台 → 创建角色 → 创建成员（生成 Token）→ 创建团队 → 配置 Agent → 初始化环境 → 领取任务

然后就可以在管理后台向 Agent 派发任务，Agent 会自动领取、执行并反馈。

---

3. 配置 Agent（MCP 接入）

Agent Token 在管理后台「成员管理」中为成员生成。

TaskMCP 支持两种接入方式：

• SSE 模式（推荐）：MCP 服务端运行在固定端口，多个 Agent 通过 HTTP 连接，各自携带 Token 区分身份
• stdio 模式：每个 Agent 启动独立子进程，适合单机开发

SSE 模式（多 Agent 共享）

服务端启动 MCP SSE：

cd taskmcp-server
MCP_TRANSPORT=sse uv run python mcp_server.py  # 默认监听 0.0.0.0:8001

所有 Agent 统一连接同一个地址，各自在请求头中携带自己的 Token：

Claude Code

{
  "mcpServers": {
    "taskmcp": {
      "type": "sse",
      "url": "http://127.0.0.1:8001/sse",
      "headers": {
        "Authorization": "Bearer <你的 Agent Token>"
      }
    }
  }
}

Claude Desktop

{
  "mcpServers": {
    "taskmcp": {
      "type": "sse",
      "url": "http://127.0.0.1:8001/sse",
      "headers": {
        "Authorization": "Bearer <你的 Agent Token>"
      }
    }
  }
}

OpenCode / Workduudy

{
  "mcpServers": {
    "taskmcp": {
      "type": "sse",
      "url": "http://127.0.0.1:8001/sse",
      "headers": {
        "Authorization": "Bearer <你的 Agent Token>"
      }
    }
  }
}

每个 Agent 使用不同的 Token 连接，MCP 服务端自动识别调用者身份，互不干扰。

stdio 模式（单 Agent 本地开发）

{
  "mcpServers": {
    "taskmcp": {
      "command": "uv",
      "args": ["run", "python", "mcp_server.py"],
      "cwd": "path/to/taskmcp-server",
      "env": {
        "TASKMCP_API_URL": "http://127.0.0.1:8000",
        "MCP_AGENT_TOKEN": "<你的 Agent Token>"
      }
    }
  }
}

连接远程后端

服务端部署在服务器时，只需将 URL 改为服务器地址：

{
  "url": "https://your-server.com:8001/sse",
  "headers": {
    "Authorization": "Bearer <你的 Agent Token>"
  }
}

环境变量说明

变量	必需	说明
MCP_AGENT_TOKEN	stdio 必需	Agent 的成员 Token
TASKMCP_API_URL	否	后端地址，默认 http://127.0.0.1:8000
DEFAULT_ADMIN_TOKEN	否	管理员 Token，默认从 docker-compose.yml 读取
MCP_TRANSPORT	否	sse（多 Agent 模式）或 stdio（默认）
MCP_PORT	否	SSE 模式端口，默认 8001

---

项目结构

taskmcp/
├── taskmcp-server/              # Python 后端
│   ├── src/taskmcp/
│   │   ├── main.py              # FastAPI 入口
│   │   ├── config.py            # 配置管理
│   │   ├── database.py          # SQLAlchemy async engine
│   │   ├── models.py            # ORM 模型
│   │   ├── constants.py         # 常量定义
│   │   ├── routers/             # API 路由
│   │   │   ├── auth.py          # 认证
│   │   │   ├── admin.py         # 管理员
│   │   │   ├── members.py       # 成员管理
│   │   │   ├── roles.py         # 角色管理
│   │   │   ├── tasks.py         # 任务管理
│   │   │   └── groups.py        # 群组管理
│   │   ├── services/            # 业务逻辑
│   │   ├── schemas/             # Pydantic 模型
│   │   ├── security/            # 安全工具
│   │   └── dependencies/        # 依赖注入
│   ├── config/                  # YAML 配置文件
│   │   ├── base.yaml            # 基础配置
│   │   ├── dev.yaml             # 开发环境
│   │   └── prod.yaml            # 生产环境
│   ├── docs/                    # 文档
│   └── mcp_server.py            # MCP Server 入口
│
├── task-dispatch/               # React 前端
│   ├── src/
│   │   ├── App.tsx              # 主应用
│   │   ├── api/                 # API 客户端
│   │   ├── stores/              # Zustand 状态
│   │   └── components/          # UI 组件
│   └── package.json
│
├── taskmcp-agent.md             # Agent 协作技能文件
└── LICENSE

---

MCP 工具

工具	说明
download_skill	下载 Agent 协作技能文件
get_todo_task	拉取待办任务（自动领取）
get_claimed_tasks	查看进行中的任务
get_completed_tasks	查看已完成的任务
send_task	向另一个 Agent 派发任务
complete_task	完成单个任务
complete_all_tasks	一键完成所有进行中任务
reject_task	拒绝任务（附原因）

---

技术栈

层	技术
后端语言	Python 3.14
Web 框架	FastAPI (异步)
ORM	SQLAlchemy 2.x (async, aiosqlite)
数据库	SQLite (零部署，生产可切换 PostgreSQL)
配置	pydantic-settings + YAML
包管理	uv
前端框架	React 18 + TypeScript
构建工具	Vite
样式	Tailwind CSS + Radix UI + Ant Design
API 文档	Scalar (/docs)

---

配置

环境变量

复制 taskmcp-server/config/.env.example 为 .env：

APP_ENV=dev              # dev | prod
DEFAULT_ADMIN_TOKEN=xxx  # 管理员 Token

配置优先级

环境变量 > .env > YAML (环境特定) > YAML (base) > 代码默认值

---

☕ 支持项目

如果 TaskMCP 为你的工作带来了便利，不妨请开发者喝杯咖啡 ☕

你的每一份支持，都是这个项目持续迭代的动力。

---

贡献

欢迎提交 Issue 和 Pull Request。详见 CONTRIBUTING.md。

许可

MIT License