Monday

🌟 概览

此代码库由 monday.com AI 团队维护，为希望与 monday.com 集成的 AI Agent 开发者提供了一套全面的工具。无论你是在构建 AI 助手、自动化流程还是自定义集成，我们的工具都能让你轻松连接到 monday.com 平台。

👉 初次接触 monday MCP？从这里开始：monday.com/w/mcp

https://github.com/user-attachments/assets/ed8d24e1-256b-4f6b-9d84-38e54a8703fd

🔑 什么是 monday.com？

monday.com 是一个工作操作系统，帮助团队运行流程、项目和日常工作。团队使用 monday.com 在一个集中的平台上规划、跟踪和管理工作。它提供了直观的可视化界面，团队可以：

• 使用可自定义的看板创建和管理项目
• 通过状态列跟踪任务在不同阶段的进度
• 通过动态和提及与团队成员协作
• 自动化工作流并与其他工具集成
• 使用仪表板和报告可视化数据

📦 包含内容

💻 monday API MCP 服务

@mondaydotcomorg/monday-api-mcp 软件包提供了一个即插即用的 Model Context Protocol（MCP）服务实现。它使 AI Agent 无需构建复杂集成，即可与 monday.com API 交互。

🤖 Agent 工具包

@mondaydotcomorg/agent-toolkit 软件包提供了一套强大的工具和实用程序，用于构建与 monday.com API 交互的 AI Agent，同时支持 OpenAI 和 Model Context Protocol（MCP）实现。

🚀 快速开始：托管 MCP（推荐）

这是连接到 monday.com 最快速、最稳健、最可靠的方式。 我们的托管 MCP 服务会为你处理所有基础设施工作——无需本地设置、自动更新，性能也更出色。

📚 集成指南

快速开始使用你喜爱的 AI 平台：

• 入门指南 - 第一次使用 monday MCP？
• Claude 集成 - 连接 Claude Desktop
• Cursor 集成 - 与 Cursor IDE 集成
• ChatGPT 集成 - 连接 ChatGPT
• MS Copilot 集成 - 与 Microsoft Copilot Studio 集成
• Mistral 集成 - 连接 Mistral AI 的 le Chat
• 开箱即用的提示词 - 帮助快速上手的示例提示词

使用托管 MCP 快速设置

适用于 Cursor

只需将以下内容添加到 MCP 设置中：

{
  "mcpServers": {
    "monday-mcp": {
      "url": "https://mcp.monday.com/mcp"
    }
  }
}

为什么使用托管 MCP？

• ✅ 无需本地安装 - 无需设置即可立即使用
• ✅ 自动更新 - 始终获得最新功能
• ✅ 性能更佳 - 经过优化的基础设施
• ✅ OAuth 身份验证 - 安全的令牌管理
• ✅ 工作区控制 - 限制对特定工作区的访问
• ✅ 更高的可靠性 - 企业级正常运行时间

何时改用此仓库

如果你需要以下功能，可能会想要在本地运行 MCP 或使用 Agent 工具包：

• 🔧 自定义 MCP 服务 - 修改源代码以满足特定需求
• 🛠️ 构建自定义 Agent - 使用 Agent 工具包实现 OpenAI 或自定义方案
• 🔌 离线工作 - 无需互联网连接即可开发
• 🧪 参与开发 - 帮助改进 MCP 服务或工具包

🏁 本地安装指南

步骤 1：创建 monday.com 账户

如果你还没有 monday.com 账户：

1. 前往 monday.com 并注册账户
2. 创建你的第一个工作区和看板，即可开始使用

步骤 2：生成 API 令牌

要与 monday.com 的 API 交互，你需要 API 令牌：

1. 登录 monday.com 账户
2. 点击左下角的头像
3. 选择“Developers”
4. 点击左侧菜单中的“My access tokens”
5. 复制你的个人访问令牌

步骤 3：配置 MCP 客户端

适用于 Claude Desktop

1. 打开 Claude Desktop
2. 前往 Settings → MCP Servers
3. 使用以下配置添加新服务：

{
  "mcpServers": {
    "monday-api-mcp": {
      "command": "npx",
      "args": [
        "@mondaydotcomorg/monday-api-mcp@latest"
      ],
      "env": {
        "MONDAY_TOKEN": "your_monday_api_token"
      }
    }
  }
}

适用于 Gemini CLI

要开始使用 Gemini CLI，你可以使用适用于 monday.com 的官方 Gemini CLI 扩展。

Gemini CLI 扩展包含 monday.com MCP 服务、上下文文件和自定义命令，可教会 Gemini 如何使用 monday.com 工具构建强大的工作流。

在终端中运行以下命令以安装扩展：

gemini extensions install https://github.com/mondaycom/mcp

如果你更希望直接使用 MCP 服务而不安装扩展，可以运行以下命令添加：

gemini mcp add -t http monday https://mcp.monday.com/mcp

安装扩展或添加 MCP 服务后，运行以下命令启动 Gemini CLI：

gemini

然后，在 Gemini CLI 中运行以下命令，使用你的 monday.com 账户进行身份验证：

/mcp auth monday

这会打开浏览器窗口以完成身份验证。 完成身份验证后，即可使用所有 monday.com 工具和自定义命令。

可以尝试以下几个扩展自定义命令：

• /monday:create-item 在看板 123 中创建“Update the UI”事项
• /monday:sprint-summary 获取冲刺 853 的摘要

适用于 Cursor 或其他 MCP 客户端（本地设置）

添加到你的设置中：

{
  "mcpServers": {
    "monday-api-mcp": {
      "command": "npx",
      "args": [
        "@mondaydotcomorg/monday-api-mcp@latest"
      ],
      "env": {
        "MONDAY_TOKEN": "your_monday_api_token"
      }
    }
  }
}

步骤 5：测试集成

1. 向 Claude 或你的 AI 助手提出类似以下问题：

   • “看板 123 中有哪些项目？”
   • “你能创建一个看板来管理我的项目吗？”

2. 现在，你的助手应该能够与 monday.com 账户交互了！

⚙️ 高级托管 MCP 配置

使用授权标头

如需在托管 MCP 中指定自定义授权标头和 API 版本：

{
  "mcpServers": {
    "monday-api-mcp-hosted": {
      "command": "npx",
      "args": [
        "-p",
        "node@20",
        "mcp-remote",
        "https://mcp.monday.com/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer <your_token>"
      }
    }
  }
}

指定 API 版本

你可以使用 --header 参数指定要使用的 API 版本：

{
  "mcpServers": {
    "monday-api-mcp-hosted": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.monday.com/mcp",
        "--header",
        "Api-Version:${API_VERSION}"
      ],
      "env": {
        "API_VERSION": "2025-07"
      }
    }
  }
}

安装 Monday MCP 应用

如需使用 OAuth 身份验证和工作区控制，请从应用市场安装 Monday MCP 应用：

1. 访问 应用市场中的 monday MCP 应用
2. 点击“Install”，并按照说明将其添加到账户

🧰 可用工具

我们的 MCP 服务提供了丰富的工具集，让 AI 助手能够与 monday.com 交互：

类别	工具	描述
项目操作	create_item	在 monday.com 看板中创建新项目，并设置指定的列值
	delete_item	永久删除看板中的项目
	get_board_items_by_name	根据看板 ID 和词语/名称搜索项目
	create_update	为特定项目添加更新/评论
	change_item_column_values	修改现有项目的列值
	move_item_to_group	将项目移动到同一看板中的其他分组
看板操作	create_board	创建包含指定列的 monday.com 新看板
	get_board_schema	获取看板的列和分组结构
	create_group	在 monday.com 看板中创建新分组
	create_column	向现有看板添加新列
	delete_column	从看板中移除一列
账户操作	list_users_and_teams	通过 ID、名称或搜索账户，获取用户或团队的详细信息
WorkForms 操作	create_form	创建新的 monday.com 表单
	get_form	根据令牌获取表单

🎨 monday.com 应用框架工具

想在 AI 助手的帮助下构建自定义 monday.com 应用吗？应用框架工具让 AI Agent 能够全面访问 monday.com 应用开发平台，使你可以直接通过 AI 助手创建、管理和部署自定义应用。

📖 查看完整的应用框架工具文档

🔮 动态 API 工具（Beta）

动态 API 工具功能代表着 AI Agent 与 monday.com 交互方式的一项重大进步。标准工具涵盖常见操作，而动态 API 工具则释放了 monday.com GraphQL API 的全部潜力。

什么是动态 API 工具？

动态 API 工具让 AI Agent 能够全面、灵活地访问 monday.com 的整个 API。也就是说，你的 AI 助手可以：

1. 访问任意 API 端点——不仅限于我们预先构建的操作
2. 生成自定义 GraphQL 查询——针对任何情况，创建所需的确切查询
3. 动态探索 monday.com 的架构——了解所有可用的数据类型及其关系

主要动态 API 工具

工具	描述
all_monday_api	动态生成并执行任意 GraphQL 查询或变更
get_graphql_schema	获取 monday.com 的 GraphQL 架构，以了解可用操作
get_type_details	获取特定 GraphQL 类型的详细信息

解锁的可能性

使用动态 API 工具，AI 助手可以：

• 创建复杂报告，涵盖多个看板、项目和数据点
• 执行批量操作，同时处理多个项目
• 深度集成 monday.com 的高级功能，例如文档、工作区和活动日志
• 发现新功能，随着 monday.com 向其 API 添加功能而不断拓展

如何启用

动态 API 工具处于 Beta 阶段，默认禁用。使用以下命令启用：

MONDAY_TOKEN=your_monday_api_token npx @mondaydotcomorg/monday-api-mcp@latest --enable-dynamic-api-tools true

你也可以使用“only”模式，仅启用动态 API 工具：

MONDAY_TOKEN=your_monday_api_token npx @mondaydotcomorg/monday-api-mcp@latest --enable-dynamic-api-tools only

启用“only”模式后，服务将只提供动态 API 工具，并过滤掉所有其他标准工具。这适用于希望直接使用 GraphQL API 的高级用户。

⚠️ 注意：动态 API 工具需要完整的 API 访问权限，且与只读模式不兼容。

🖥️ MCP 服务配置

参数	标志	说明	必填	默认值
monday.com API 令牌	--token、-t	monday.com API 令牌	是	-
API 版本	--version、-v	monday.com API 版本	否	current
模式	--mode、-m	工具模式：default 表示标准平台工具，apps 表示 Apps Framework 工具	否	default
只读模式	--read-only、-ro	启用只读模式	否	false
动态 API 工具	--enable-dynamic-api-tools、-edat	启用动态 API 工具	否	false

🔐 身份验证与安全

该服务需要 monday.com API 令牌才能通过 monday.com API 进行身份验证。你可以通过以下两种方式提供此令牌：

1. 环境变量：MONDAY_TOKEN=your_monday_api_token
2. 命令行参数：-t your_monday_api_token

安全最佳实践

• 切勿在公开仓库或讨论中分享 API 令牌
• 如果只需检索数据，请考虑使用只读模式（--read-only）
• 定期轮换 API 令牌，以增强安全性

📚 示例用例

以下是一些可以使用我们的工具构建的示例：

1. 项目管理 AI 助手

• 在 monday.com 看板中创建和管理任务
• 获取项目状态更新
• 随着进展在组之间移动项目

2. 数据分析与报告

• 从 monday.com 看板提取数据
• 生成报告和洞察
• 创建用于报告的新看板

🌐 社区与支持

• GitHub Issues：用于提交 Bug 报告和功能请求
• 讨论区：用于提问和社区讨论
• monday.com 开发者文档：了解有关 monday.com API 的更多信息

📚 文档

• monday API MCP 文档
• Agent Toolkit 文档
• monday.com API 参考

📋 前提条件

使用这些工具前，请确保已安装：

1. Node.js v20 或更高版本
2. NPM v5.2.0 或更高版本
3. monday.com API 令牌

🛠️ 如何在仓库中开发

在仓库中进行开发：

1. 克隆仓库
2. 安装依赖项：yarn install
3. 构建项目：yarn build
4. 复制 monday-api-mcp 包中 dist/index.js 文件的路径。
5. 修改配置以在本地运行

    "monday-api-mcp": {
      "command": "node",
      "args": [
        "<your_full_path_to_the_package>/dist/index.js",
        "--enable-dynamic-api-tools",
        "true"
      ],
      "env": {
        "MONDAY_TOKEN": "your_monday_api_token"
      }
    }

🤝 参与贡献

欢迎社区贡献！无论是修复 Bug、改进文档还是添加新功能，我们都非常感谢你的帮助。

1. Fork 仓库
2. 创建功能分支：git checkout -b feature/amazing-feature
3. 提交更改：git commit -m 'Add some amazing feature'
4. 推送到分支：git push origin feature/amazing-feature
5. 创建 Pull Request

📄 许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

特此说明，服务使用 monday.com API，该 API 受 monday.com 的开发者条款约束。

---