Monday MCP

Monday.com MCP服务器

一个模型上下文协议（MCP）服务器，提供与Monday.com API交互的工具。此服务器使AI助手能够从Monday.com工作区检索板列表、板详细信息、项目内容和用户信息。

什么是MCP？

模型上下文协议（MCP）是一种开放协议，使AI应用程序能够连接到外部数据源和工具。MCP服务器公开了工具、资源和提示，可供Claude等AI助手使用，以执行操作和访问信息。

特性

• 董事会管理：从Monday.com工作区检索分页的电路板列表
• 董事会详细信息：获取具有过滤项目的特定板的详细信息
• 物品内容：获取特定板项的详细内容，包括解析的描述
• 用户信息：检索有关当前已验证用户的信息
• 标准运输：使用标准输入/输出进行沟通（非常适合当地发展）
• TypeScript：用TypeScript编写，用于类型安全和更好的开发人员体验
• Zod验证：使用Zod对工具输入和输出进行模式验证
• 错误处理：通过用户友好的消息进行全面的错误处理

先决条件

• Node.js（建议使用v18或更高版本）
• npm或纱线
• 具有API访问权限的Monday.com帐户
• 星期一.com API令牌

安装

1. 克隆或下载此存储库
2. 安装依赖项：

npm install

1. 将您的Monday.com API令牌设置为环境变量：

export MONDAY_API_TOKEN="your_api_token_here"

或者创建一个 .env 项目根目录中的文件：

MONDAY_API_TOKEN=your_api_token_here

获取您的Monday.com API代币

1. 登录您的Monday.com帐户
2. 点击左下角的头像
3. 导航至 行政 → API
4. 生成新的API令牌或复制现有令牌
5. 复制令牌并安全保存

建筑

将TypeScript编译为JavaScript：

npm run build

这将在 dist/ 目录。

运行服务器

生产模式

构建后，运行编译后的服务器：

npm start

发展模式

直接使用TypeScript运行服务器（不需要构建步骤）：

npm run dev

服务器将启动并通过stdio（标准输入/输出）监听MCP请求。

可用工具

服务器提供了四种与Monday.com交互的工具：

1. monday_get_board_list

从Monday.com工作区检索分页的电路板列表。

参数：

• limit （数字，可选）：返回的最大板数（默认值：10）
• page （数字，可选）：分页页码（默认值：1）

退货：

• 带有ID、名称、描述、项目术语、状态和视图的板对象数组

示例用法：

// Get first 10 boards
{ limit: 10, page: 1 }

// Get 25 boards from page 2
{ limit: 25, page: 2 }

2. monday_get_board_details

使用筛选项目（分配给我并准备开始）检索特定板的详细信息。

参数：

• boardId （string，必填）：用于检索详细信息的板的ID

退货：

• 具有符合条件的筛选项目的Board对象

示例用法：

{ boardId: "1234567890" }

3. monday_get_board_item_list

检索特定板项的详细内容，包括解析的描述文本。

参数：

• itemId （string，必填）：要检索内容的项目的ID

退货：

• 带有id、名称和清晰描述文本的项目对象（已过滤掉图像）

示例用法：

{ itemId: "9876543210" }

4. monday_get_me

检索有关当前经过身份验证的Monday.com用户的信息。

参数：

• 无

退货：

• 带有配置文件详细信息（id、姓名、电子邮件等）的用户对象

示例用法：

// No parameters needed
{}

项目结构

mat-monday-mcp-server/
├── src/
│   ├── index.ts                      # Main server implementation
│   ├── types.ts                      # Type definitions
│   ├── config/
│   │   └── client.ts                 # Monday.com API client configuration
│   ├── services/
│   │   ├── boards.ts                 # Board-related API operations
│   │   ├── items.ts                  # Item-related API operations
│   │   ├── monday.ts                 # Core Monday.com service
│   │   └── users.ts                  # User-related API operations
│   ├── tools/
│   │   ├── index.ts                  # Tool registry
│   │   ├── get-board-list.ts         # Board list tool
│   │   ├── get-board-details.ts      # Board details tool
│   │   ├── get-board-item-content.ts # Item content tool
│   │   └── get-me.ts                 # Current user tool
│   └── utils/
│       └── content-parser.ts         # Content parsing utilities
├── dist/                             # Compiled JavaScript (generated)
├── package.json                      # Project dependencies and scripts
├── tsconfig.json                     # TypeScript configuration
├── tsup.config.ts                    # Build configuration
└── README.md                         # This file

运作原理

建筑

1. 服务器创建：服务器是使用创建的 McpServer 从 @modelcontextprotocol/sdk
2. 工具注册：所有工具都通过中心注册 registerTools 函数
3. 服务层：业务逻辑分为服务模块（板、项目、用户）
4. Monday.com客户端：API交互使用官方 @mondaydotcomorg/api 软件开发工具包
5. 传输设置：服务器通过以下方式连接 StdioServerTransport 用于stdio通信
6. 请求处理：当客户端调用工具时，它会执行相应的服务功能

服务

董事会服务(services/boards.ts)

• getBoardListPaginated(limit, page)：获取分页的电路板列表
• getBoardDetailsPaginated(boardId)：使用筛选项目获取董事会详细信息

项目服务(services/items.ts)

• getBoardItemContent(itemId)：获取具有解析描述的项目内容

用户服务(services/users.ts)

• getMe()：获取当前经过身份验证的用户信息

内容解析

服务器包括解析Monday.com描述格式的实用程序：

• 从类似Quill的deltaFormat结构中提取干净的文本
• 过滤掉图像块
• 提供可读的文本内容

与MCP客户端一起使用

要将此服务器与MCP客户端（如Claude Desktop或Cursor）一起使用，您需要在MCP客户端设置中对其进行配置。服务器通过stdio进行通信，因此客户端需要生成服务器进程。

客户端配置示例

对于Claude Desktop，添加到您的 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "monday": {
      "command": "node",
      "args": ["/path/to/mat-monday-mcp-server/dist/index.js"],
      "env": {
        "MONDAY_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

对于Cursor，添加到您的 ~/.cursor/mcp.json:

{
  "mcpServers": {
    "monday": {
      "command": "node",
      "args": ["/path/to/mat-monday-mcp-server/dist/index.js"],
      "env": {
        "MONDAY_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

发展

脚本

• npm run build -使用tsup将TypeScript编译为JavaScript
• npm start -运行已编译的服务器
• npm run dev -使用TypeScript直接运行服务器（开发模式）

依赖项

• @modelcontextprotocol/sdk -TypeScript/Node.js的官方MCP SDK
• @mondaydotcomorg/api -官方星期一网站API SDK
• zod -模式验证库
• typescript -TypeScript编译器
• tsup -用于构建的TypeScript绑定器

添加新工具

要添加新工具，请执行以下操作：

1. 在中创建新文件 src/tools/ （例如。， my-new-tool.ts)
2. 定义a ToolDefinition 包含名称、配置和处理程序
3. 导入 src/tools/index.ts
4. 将其添加到 tools 数组中 registerTools 函数

例子：

// src/tools/my-new-tool.ts
import { z } from 'zod'
import type { ToolDefinition } from '../index'

export const myNewTool: ToolDefinition = {
  name: 'monday_my_new_tool',
  config: {
    title: 'My New Tool',
    description: 'Description of what this tool does',
    inputSchema: {
      param: z.string().describe('Description of parameter')
    },
    outputSchema: {
      result: z.any().describe('Result description')
    }
  },
  handler: async (inputs: any) => {
    try {
      // Tool logic here
      return {
        content: [{ type: 'text', text: 'Success message' }],
        structuredContent: { result: {} }
      }
    } catch (error) {
      const errorMessage = error instanceof Error ? error.message : 'Unknown error'
      return {
        content: [{ type: 'text', text: `Error: ${errorMessage}` }],
        structuredContent: {
          result: { error: true, type: 'ErrorType', message: errorMessage }
        }
      }
    }
  }
}

错误处理

所有工具都包括全面的错误处理：

• 错误被捕获并以人类可读的格式返回(content)结构化格式(structuredContent)
• 错误响应包括错误类型和消息
• 妥善处理网络错误、身份验证问题和API错误

学习资源

• 模型上下文协议文档
• MCP TypeScript SDK
• API周一文档
• 星期一API SDK

许可证

ISC