ClickMongrel-点击克劳德MCP服务器
一个模型上下文协议（MCP）服务器，将Claude的TodoWrite与ClickUp无缝集成，提供自动任务同步、提交跟踪、时间管理和全面的项目跟踪。
📚 查看完整文档
🚀 特性
核心功能
- 🔄 自动TodoWrite同步 -在Claude中创建的任务会自动同步到ClickUp
- 👨👩👧👦 亲子任务关系 -具有自动父级状态管理的子任务
- ⏱️ 时间跟踪 -任务完成时自动跟踪时间
- 📝 提交链接 -将已完成的任务链接到其提交
- 📎 附件支持 -将屏幕截图、演示和文件上传到任务
- 👤 自动分配 -自动分配给已配置用户的任务
- 📊 状态生命周期 -通过自定义ClickUp状态跟踪任务
- 🎯 目标管理 -跟踪项目目标和进度
- 📈 报告生成 -每日和每周开发报告
增强功能（新增）
- 智能时间追踪 -自动跟踪从任务开始到完成的时间
- 任务提交关系 -将任务链接到完成任务的提交
- 附件上传 -添加屏幕截图和演示以展示功能
- 父任务自动完成 -当所有子任务完成时，父任务自动完成
📋 先决条件
- 点击账户 具有API访问权限
- 克劳德代码 支持MCP
- Node.js 18+和pnpm
- 点击API键 -从ClickUp设置获取→ Apps → API代币
🛠️ 安装
选项1：来自GitHub（推荐）
# Clone the repository
git clone https://github.com/yourusername/clickmongrel.git
cd clickmongrel
# Install dependencies
pnpm install
# Build the project
pnpm run build
# Test connection
CLICKUP_API_KEY="your_api_key" node dist/cli.js test选项2:NPM全局安装（即将推出）
npm install -g @clickmongrel/mcp-server⚙️ 设置
快速设置（AI友好）
当使用Claude和ClickMongrel时，只需说：
- “安装程序单击\[您的工作区名称\]”
- “在\[工作区\]的\[空间名称\]中设置clickmongrel”
手动设置
# Basic setup - uses default "Agentic Development" space
node dist/quick-setup.js --workspace "Your Workspace Name"
# Setup with specific space
node dist/quick-setup.js --workspace "Your Workspace" --space-name "Custom Space"
# Setup with space ID (faster)
node dist/quick-setup.js --workspace "Your Workspace" --space-id "90139256288"🔌 MCP集成
添加到克劳德代码
# Add the MCP server (NEVER put API key in config files!)
claude mcp add clickmongrel \
--env CLICKUP_API_KEY="your_api_key_here" \
-- node /absolute/path/to/clickmongrel/dist/index.js
# Verify it's connected
claude mcp list
# In Claude Code, check status
/mcp可用的MCP工具
| 工具 | 说明 | 示例用法 |
|---|---|---|
sync_todos | 将TodoWrite项目同步到ClickUp | 使用TodoWrites时自动 |
add_attachment | 将文件上传到任务 | “向此任务添加屏幕截图” |
create_goal | 创建项目目标 | “为身份验证功能创建目标” |
link_commit | 链接提交到任务 | 提交时自动 |
generate_report | 创建状态报告 | “生成周报” |
validate_statuses | 检查ClickUp配置 | “验证ClickUp状态” |
📁 项目结构
your-project/
└── .claude/
└── clickup/
├── config.json # Workspace & list IDs (NO API KEYS!)
├── STATUS_SETUP_GUIDE.md # Instructions for ClickUp setup
├── templates/ # Commit message templates
├── reports/ # Generated reports
└── cache/ # Temporary cache⚠️ 关键：点击状态配置
在ClickUp中配置自定义状态之前，系统将无法工作！
所需任务状态
- 转到ClickUp→ 您的共享空间→ 任务列表
- 点击⋮菜单→ “编辑状态”
- 选择“自定义状态”
- 添加以下精确状态：
- to do - future - in progress - fixing - completed
所需提交状态
- 转到ClickUp→ 您的共享空间→ 承诺清单
- 点击⋮菜单→ “编辑状态”
- 添加以下精确状态：
- comitted - developing - prototyping - rejected - production/testing - production/final
🎯 使用示例
基本任务管理
// Claude TodoWrite automatically syncs
TodoWrite([
{ id: "task-1", content: "Setup database", status: "pending" },
{ id: "task-2", content: "Create API", status: "in_progress" }
])父子任务
// Create tasks with subtasks
TodoWrite([
{ id: "feature", content: "User Authentication", status: "pending" },
{ id: "sub-1", content: "Login form", status: "pending", parent_id: "feature" },
{ id: "sub-2", content: "JWT tokens", status: "pending", parent_id: "feature" }
])
// Parent auto-updates to "in_progress" when subtask starts
// Parent auto-completes when all subtasks complete增强功能
// Time tracking (automatic)
// When task goes from in_progress → completed, time is tracked
// Add attachments
mcp.add_attachment({
task_id: "task-1",
file_path: "/path/to/screenshot.png",
file_name: "Dashboard Screenshot"
})
// Tasks automatically link to commits that complete them🔧 配置
环境变量
CLICKUP_API_KEY=pk_xxx # Your ClickUp API key (REQUIRED)
CLICKUP_WORKSPACE_ID=xxx # Optional: Default workspace
CLICKUP_SPACE_ID=xxx # Optional: Default space
LOG_LEVEL=info # Logging level (debug|info|warn|error)安全最佳实践
⚠️ 切勿将API密钥存储在：
- 配置文件(
.json,.env) - Git仓库
- 项目目录
✅ 始终通过以下方式传递API密钥：
--env添加MCP时标记- 运行时的环境变量
- Claude Code的安全存储
📊 详细功能
时间跟踪
- 任务状态时自动启动→
in_progress - 停止并记录状态时间→
completed - 用实际花费的时间更新ClickUp
提交链接
- 每次提交都会在提交列表中创建一个任务
- 已完成的任务链接到其最终提交
- 完整的开发可追溯性
附件支持
- 上传屏幕截图、文档或任何文件
- Claude可以提示：“您想添加屏幕截图吗？”
- 直接附加到ClickUp任务的文件
父任务管理
- 父任务根据子任务自动更新
- 状态流：
pending→in_progress→completed - 所有子任务完成后自动完成
🐛 故障排除
“状态验证失败”
- 在ClickUp中配置自定义状态（请参阅上面的状态配置）
- 跑
clickmongrel check-statuses验证
“没有可用的列表ID”
- 再次运行安装程序：
node dist/quick-setup.js --workspace "Your Workspace"
“API密钥无效”
- 检查API密钥是否正确
- 确保它通过
--env标志，不在配置文件中
任务未同步
- 检查状态是否已配置
- 验证是否设置了API密钥
- 确保工作空间/空间正确
- 检查日志：
LOG_LEVEL=debug node dist/index.js
🤝 贡献
欢迎投稿！拜托：
- 分叉存储库
- 创建要素分支
- 进行更改
- 如果适用，添加测试
- 提交拉取请求
📄 许可证
MIT许可证-有关详细信息，请参阅许可证文件
🔗 链接
💡 Claude用户提示
- 让Claude处理设置：告诉克劳德你的工作区名称
- 使用自然语言：“为此功能创建目标”
- TodoWrite集成：自动-只需正常使用TodoWrite
- 请求附件：Claude可以提示截图
- 检查进度：“显示同步状态”或“验证状态”
🚨 重要提示
- 这是一个PUBLIC项目-永远不要在代码中引用特定的工作区
- API密钥不得存储在项目文件中
- 始终对敏感数据使用环境变量
- 首次使用前配置ClickUp状态
______________________________________________________________________
专为使用Claude Code和ClickUp集成需求的开发人员而构建