mcp-wecom-smartsheet

v2.0.0

Published

3 months ago

MCP server for WeChat Work (WeCom) SmartSheet integration

Downloads

0High
0Medium
0Low

afengz

mcp wecom smartsheet wechat-work model-context-protocol

WeChat Work (WeCom) SmartSheet MCP Server

一个用于对接企业微信智能表格的 MCP (Model Context Protocol) 服务器，通过 Webhook 方式支持添加记录功能。

功能特性

✅ 通过 Webhook 添加记录到智能表格
✅ 支持多种字段类型：文本、数字、复选框、日期、图片、人员、链接、单选/多选、进度、电话、邮箱、地理位置、货币、百分数、条码
✅ 支持批量操作（最多 100 条记录）
✅ 环境变量配置 Webhook URL 和字段 Schema
✅ 智能自然语言添加功能

⚠️ 重要限制

根据企业微信 Webhook 接口的实际限制：

仅支持添加记录：Webhook 接口仅支持添加记录，不支持更新记录
必须使用字段 ID：添加记录时必须使用智能表格的字段 ID（如 ftk5Tx），不能使用字段名称
需要配置 Schema：必须在环境变量中配置字段 ID 与字段名称的映射关系
更新功能限制：更新记录功能需要使用企业微信内部接口，需要 access_token，当前版本由于无法接入获取 access_token 的流程，暂不支持更新功能

为什么不支持更新记录？

企业微信智能表格的更新记录功能需要通过企业微信内部 API 调用，该 API 需要有效的 access_token。获取 access_token 需要：

企业微信应用的 corpid 和 corpsecret
完整的认证流程和 token 刷新机制

由于 MCP 工具的设计目标是轻量级和易配置，当前版本仅支持通过 Webhook 添加记录。如果需要更新功能，需要：

配置企业微信应用的 corpid 和 corpsecret
实现 access_token 的获取和刷新机制
调用企业微信内部 API 进行更新

后续版本计划：如果用户有强烈需求，可以考虑在后续版本中添加更新功能支持。

前置要求

企业微信账号
企业微信智能表格

安装

方式 1: 从源码安装

git clone <repository-url>
cd mcp-server
npm install
npm run build

方式 2: 使用 npm 全局安装（推荐）

npm install -g mcp-wecom-smartsheet

方式 3: 使用 npx（无需安装）

直接在 MCP 配置中使用 npx 命令，无需预先安装（见下方 MCP 配置）。

配置

获取 Webhook URL

打开企业微信智能表格
点击右上角「...」菜单
选择「接收外部数据」

开启该功能后，会显示完整的 Webhook 地址，格式为：

https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/webhook?key=YOUR_WEBHOOK_KEY

复制完整的 Webhook 地址

获取字段 ID 和配置 Schema

在智能表格中，点击表头字段
查看字段属性，找到字段 ID（通常以 f 开头，如 ftk5Tx）
记录所有需要使用的字段 ID 和对应的字段名称
将字段 ID 和名称映射配置到环境变量中

Schema 配置支持两种格式：

格式 1：简单格式（仅包含字段 ID 和名称）

适用于只需要基本字段信息的场景：

{
  "ftk5Tx": "员工",
  "f04Gwj": "客户名称",
  "ftawan": "客户电话",
  "ftQMc5": "单选",
  "ffFwIh": "金额",
  "fn8TJd": "添加客户时间",
  "fo3Koj": "结单时间"
}

格式 2：详细格式（包含字段类型、是否必填、选项等）

适用于需要 AI 更好理解字段要求的场景：

{
  "ftk5Tx": {
    "fieldName": "员工",
    "fieldType": "FIELD_TYPE_USER",
    "required": true,
    "description": "负责该客户的员工"
  },
  "f04Gwj": {
    "fieldName": "客户名称",
    "fieldType": "FIELD_TYPE_TEXT",
    "required": true,
    "description": "客户的公司或个人名称"
  },
  "ftawan": {
    "fieldName": "客户电话",
    "fieldType": "FIELD_TYPE_PHONE_NUMBER",
    "required": false,
    "description": "客户联系电话"
  },
  "ftQMc5": {
    "fieldName": "单选",
    "fieldType": "FIELD_TYPE_SINGLE_SELECT",
    "required": false,
    "options": ["未结单", "已结单", "跟进中"],
    "description": "订单状态"
  },
  "ffFwIh": {
    "fieldName": "金额",
    "fieldType": "FIELD_TYPE_CURRENCY",
    "required": false,
    "description": "订单金额"
  },
  "fn8TJd": {
    "fieldName": "添加客户时间",
    "fieldType": "FIELD_TYPE_DATE_TIME",
    "required": false,
    "description": "客户添加时间"
  },
  "fo3Koj": {
    "fieldName": "结单时间",
    "fieldType": "FIELD_TYPE_DATE_TIME",
    "required": false,
    "description": "订单结单时间"
  }
}

字段类型枚举：

FIELD_TYPE_TEXT - 文本
FIELD_TYPE_NUMBER - 数字
FIELD_TYPE_CHECKBOX - 复选框
FIELD_TYPE_DATE_TIME - 日期时间
FIELD_TYPE_IMAGE - 图片
FIELD_TYPE_USER - 人员
FIELD_TYPE_URL - 链接
FIELD_TYPE_SINGLE_SELECT - 单选
FIELD_TYPE_SELECT - 多选
FIELD_TYPE_PROGRESS - 进度
FIELD_TYPE_PHONE_NUMBER - 电话
FIELD_TYPE_EMAIL - 邮箱
FIELD_TYPE_LOCATION - 地理位置
FIELD_TYPE_CURRENCY - 货币
FIELD_TYPE_PERCENTAGE - 百分数
FIELD_TYPE_BARCODE - 条码

两种格式的对比：

| 特性 | 简单格式 | 详细格式 | | ----------- | -------- | -------- | | 字段 ID | ✅ 有 | ✅ 有 | | 字段名称 | ✅ 有 | ✅ 有 | | 字段类型 | ❌ 无 | ✅ 有 | | 是否必填 | ❌ 无 | ✅ 有 | | 可选值 | ❌ 无 | ✅ 有 | | 字段描述 | ❌ 无 | ✅ 有 | | 示例值 | ❌ 无 | ✅ 有 | | AI 理解程度 | ⚠️ 基础 | ✅ 完整 |

推荐： 如果希望 AI 模型更好地理解字段要求并提供准确的数据，建议使用详细格式。

配置环境变量

复制环境变量示例文件：

cp .env.example .env

编辑 .env 文件，填入完整的 Webhook URL 和 Schema：

WECOM_WEBHOOK_URL=https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/webhook?key=your_webhook_key_here

WECOM_SMARTSHEET_SCHEMA={"ftk5Tx":"员工","f04Gwj":"客户名称","ftawan":"客户电话","ftQMc5":"单选","ffFwIh":"金额","fn8TJd":"添加客户时间","fo3Koj":"结单时间"}

注意事项：

WECOM_SMARTSHEET_SCHEMA 必须是有效的 JSON 格式
JSON 中的键是字段 ID，值是字段名称
字段名称用于智能解析功能，AI 会根据字段名称匹配输入数据

MCP 配置

完整配置示例

以下是在 Claude Desktop 或其他支持 MCP 的客户端中配置此服务器的完整示例：

方式 1: 使用 npx（推荐，无需安装）

{
  "mcpServers": {
    "wecom-smartsheet": {
      "enabled": true,
      "owner": "admin",
      "type": "stdio",
      "command": "npx",
      "args": ["mcp-wecom-smartsheet"],
      "env": {
        "WECOM_WEBHOOK_URL": "https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/webhook?key=YOUR_WEBHOOK_KEY",
        "WECOM_SMARTSHEET_SCHEMA": "{\"ftk5Tx\":\"员工\",\"f04Gwj\":\"客户名称\",\"ftawan\":\"客户电话\",\"ftQMc5\":\"单选\",\"ffFwIh\":\"金额\",\"fn8TJd\":\"添加客户时间\",\"fo3Koj\":\"结单时间\"}"
      }
    }
  }
}

详细格式示例（推荐）：

{
  "mcpServers": {
    "wecom-smartsheet": {
      "enabled": true,
      "owner": "admin",
      "type": "stdio",
      "command": "npx",
      "args": ["mcp-wecom-smartsheet"],
      "env": {
        "WECOM_WEBHOOK_URL": "https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/webhook?key=YOUR_WEBHOOK_KEY",
        "WECOM_SMARTSHEET_SCHEMA": "{\"ftk5Tx\":{\"fieldName\":\"员工\",\"fieldType\":\"FIELD_TYPE_USER\",\"required\":true,\"description\":\"负责该客户的员工\"},\"f04Gwj\":{\"fieldName\":\"客户名称\",\"fieldType\":\"FIELD_TYPE_TEXT\",\"required\":true,\"description\":\"客户的公司或个人名称\"},\"ftawan\":{\"fieldName\":\"客户电话\",\"fieldType\":\"FIELD_TYPE_PHONE_NUMBER\",\"required\":false,\"description\":\"客户联系电话\"},\"ftQMc5\":{\"fieldName\":\"单选\",\"fieldType\":\"FIELD_TYPE_SINGLE_SELECT\",\"required\":false,\"options\":[\"未结单\",\"已结单\",\"跟进中\"],\"description\":\"订单状态\"},\"ffFwIh\":{\"fieldName\":\"金额\",\"fieldType\":\"FIELD_TYPE_CURRENCY\",\"required\":false,\"description\":\"订单金额\"},\"fn8TJd\":{\"fieldName\":\"添加客户时间\",\"fieldType\":\"FIELD_TYPE_DATE_TIME\",\"required\":false,\"description\":\"客户添加时间\"},\"fo3Koj\":{\"fieldName\":\"结单时间\",\"fieldType\":\"FIELD_TYPE_DATE_TIME\",\"required\":false,\"description\":\"订单结单时间\"}}"
      }
    }
  }
}

方式 2: 全局安装后使用

npm install -g mcp-wecom-smartsheet

然后在 MCP 配置中：

{
  "mcpServers": {
    "wecom-smartsheet": {
      "enabled": true,
      "owner": "admin",
      "type": "stdio",
      "command": "mcp-wecom-smartsheet",
      "args": [],
      "env": {
        "WECOM_WEBHOOK_URL": "https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/webhook?key=YOUR_WEBHOOK_KEY",
        "WECOM_SMARTSHEET_SCHEMA": "{\"ftk5Tx\":\"员工\",\"f04Gwj\":\"客户名称\",\"ftawan\":\"客户电话\",\"ftQMc5\":\"单选\",\"ffFwIh\":\"金额\",\"fn8TJd\":\"添加客户时间\",\"fo3Koj\":\"结单时间\"}"
      }
    }
  }
}

详细格式示例（推荐）：

{
  "mcpServers": {
    "wecom-smartsheet": {
      "enabled": true,
      "owner": "admin",
      "type": "stdio",
      "command": "mcp-wecom-smartsheet",
      "args": [],
      "env": {
        "WECOM_WEBHOOK_URL": "https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/webhook?key=YOUR_WEBHOOK_KEY",
        "WECOM_SMARTSHEET_SCHEMA": "{\"ftk5Tx\":{\"fieldName\":\"员工\",\"fieldType\":\"FIELD_TYPE_USER\",\"required\":true,\"description\":\"负责该客户的员工\"},\"f04Gwj\":{\"fieldName\":\"客户名称\",\"fieldType\":\"FIELD_TYPE_TEXT\",\"required\":true,\"description\":\"客户的公司或个人名称\"},\"ftawan\":{\"fieldName\":\"客户电话\",\"fieldType\":\"FIELD_TYPE_PHONE_NUMBER\",\"required\":false,\"description\":\"客户联系电话\"},\"ftQMc5\":{\"fieldName\":\"单选\",\"fieldType\":\"FIELD_TYPE_SINGLE_SELECT\",\"required\":false,\"options\":[\"未结单\",\"已结单\",\"跟进中\"],\"description\":\"订单状态\"},\"ffFwIh\":{\"fieldName\":\"金额\",\"fieldType\":\"FIELD_TYPE_CURRENCY\",\"required\":false,\"description\":\"订单金额\"},\"fn8TJd\":{\"fieldName\":\"添加客户时间\",\"fieldType\":\"FIELD_TYPE_DATE_TIME\",\"required\":false,\"description\":\"客户添加时间\"},\"fo3Koj\":{\"fieldName\":\"结单时间\",\"fieldType\":\"FIELD_TYPE_DATE_TIME\",\"required\":false,\"description\":\"订单结单时间\"}}"
      }
    }
  }
}

方式 3: 从源码运行

{
  "mcpServers": {
    "wecom-smartsheet": {
      "enabled": true,
      "owner": "admin",
      "type": "stdio",
      "command": "node",
      "args": ["D:\\LLF\\WorkSpace\\mcp-server\\dist\\index.js"],
      "env": {
        "WECOM_WEBHOOK_URL": "https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/webhook?key=YOUR_WEBHOOK_KEY",
        "WECOM_SMARTSHEET_SCHEMA": "{\"ftk5Tx\":\"员工\",\"f04Gwj\":\"客户名称\",\"ftawan\":\"客户电话\",\"ftQMc5\":\"单选\",\"ffFwIh\":\"金额\",\"fn8TJd\":\"添加客户时间\",\"fo3Koj\":\"结单时间\"}"
      }
    }
  }
}

详细格式示例（推荐）：

{
  "mcpServers": {
    "wecom-smartsheet": {
      "enabled": true,
      "owner": "admin",
      "type": "stdio",
      "command": "node",
      "args": ["D:\\LLF\\WorkSpace\\mcp-server\\dist\\index.js"],
      "env": {
        "WECOM_WEBHOOK_URL": "https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/webhook?key=YOUR_WEBHOOK_KEY",
        "WECOM_SMARTSHEET_SCHEMA": "{\"ftk5Tx\":{\"fieldName\":\"员工\",\"fieldType\":\"FIELD_TYPE_USER\",\"required\":true,\"description\":\"负责该客户的员工\"},\"f04Gwj\":{\"fieldName\":\"客户名称\",\"fieldType\":\"FIELD_TYPE_TEXT\",\"required\":true,\"description\":\"客户的公司或个人名称\"},\"ftawan\":{\"fieldName\":\"客户电话\",\"fieldType\":\"FIELD_TYPE_PHONE_NUMBER\",\"required\":false,\"description\":\"客户联系电话\"},\"ftQMc5\":{\"fieldName\":\"单选\",\"fieldType\":\"FIELD_TYPE_SINGLE_SELECT\",\"required\":false,\"options\":[\"未结单\",\"已结单\",\"跟进中\"],\"description\":\"订单状态\"},\"ffFwIh\":{\"fieldName\":\"金额\",\"fieldType\":\"FIELD_TYPE_CURRENCY\",\"required\":false,\"description\":\"订单金额\"},\"fn8TJd\":{\"fieldName\":\"添加客户时间\",\"fieldType\":\"FIELD_TYPE_DATE_TIME\",\"required\":false,\"description\":\"客户添加时间\"},\"fo3Koj\":{\"fieldName\":\"结单时间\",\"fieldType\":\"FIELD_TYPE_DATE_TIME\",\"required\":false,\"description\":\"订单结单时间\"}}"
      }
    }
  }
}

配置参数说明

| 参数 | 必填 | 说明 | 示例 | | ----------------------------- | ---- | ------------------------------------- | ------------------------------------------------------------------------ | | enabled | 是 | 是否启用此 MCP 服务器 | true | | owner | 是 | 服务器所有者 | "admin" | | type | 是 | 通信类型，固定为 "stdio" | "stdio" | | command | 是 | 启动命令 | "npx" 或 "mcp-wecom-smartsheet" 或 "node" | | args | 否 | 命令参数 | ["mcp-wecom-smartsheet"] 或 ["D:\\path\\to\\dist\\index.js"] | | env.WECOM_WEBHOOK_URL | 是 | 企业微信智能表格 Webhook 完整地址 | "https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/webhook?key=xxx" | | env.WECOM_SMARTSHEET_SCHEMA | 是 | 字段 ID 与字段名称的映射（JSON 格式） | "{\"ftk5Tx\":\"员工\",\"f04Gwj\":\"客户名称\"}" |

配置注意事项

Webhook URL 格式：
- 必须是完整的 URL，包含 key 参数
- 示例：https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/webhook?key=YOUR_KEY
Schema JSON 格式：
- 必须是有效的 JSON 字符串
- 注意转义双引号：\" 而不是 "
- 建议使用在线 JSON 格式化工具验证格式
路径分隔符：
- Windows 系统使用双反斜杠 \\ 或正斜杠 /
- 示例："D:\\LLF\\WorkSpace\\mcp-server\\dist\\index.js"
环境变量转义：
- 在 JSON 配置中，环境变量的值需要转义特殊字符
- 特别是双引号需要转义为 \"

配置验证

配置完成后，可以通过以下方式验证配置是否正确：

查看服务器日志：

启动 MCP 客户端后，查看控制台输出

应该看到类似以下的日志：

WeChat Work SmartSheet MCP Server v2.0.0 running on stdio
Webhook URL configured: Yes
Schema configured: Yes (7 fields)

测试工具调用：
- 使用 describe_smartsheet_schema 工具查看 Schema 配置
- 如果返回成功，说明配置正确
测试添加记录：
- 使用 smart_add_smartsheet_record 工具测试添加记录
- 如果返回成功，说明 Webhook URL 和 Schema 配置都正确

使用方法

启动服务器

npm start

MCP 工具

1. 添加记录（使用字段 ID）

添加一条或多条新记录到智能表格，必须使用字段 ID：

{
  "name": "add_smartsheet_record",
  "arguments": {
    "records": [
      {
        "values": {
          "ftk5Tx": [
            {
              "user_id": ""
            }
          ],
          "f04Gwj": "测试文本",
          "ftawan": "12345678910",
          "ftQMc5": [
            {
              "text": "未结单"
            }
          ],
          "ffFwIh": 10,
          "fn8TJd": 1735660800000,
          "fo3Koj": 1735660800000
        }
      }
    ]
  }
}

返回结果包含新增记录的 record_id：

{
  "success": true,
  "message": "Successfully added 1 record(s)",
  "data": {
    "errcode": 0,
    "errmsg": "ok",
    "add_records": [
      {
        "record_id": "7TDweV",
        "values": {
          "ftk5Tx": [
            {
              "user_id": ""
            }
          ],
          "f04Gwj": "测试文本"
        }
      }
    ]
  }
}

2. 智能添加记录（使用自然语言）

使用自然语言描述数据，AI 会自动解析并匹配到对应的字段：

{
  "name": "smart_add_smartsheet_record",
  "arguments": {
    "data": "员工：张三，客户名称：ABC公司，客户电话：13800138000，单选：未结单，金额：1000，添加客户时间：2025-01-01，结单时间：2025-01-15"
  }
}

AI 会根据 Schema 中的字段名称自动匹配，并将值转换为字段 ID：

{
  "success": true,
  "message": "记录添加成功",
  "record_id": "7TDweV",
  "parsed_data": {
    "ftk5Tx": "张三",
    "f04Gwj": "ABC公司",
    "ftawan": "13800138000",
    "ftQMc5": "未结单",
    "ffFwIh": 1000,
    "fn8TJd": 1735660800000,
    "fo3Koj": 1737331200000
  }
}

3. 查看字段 Schema

查看当前配置的字段 Schema：

{
  "name": "describe_smartsheet_schema",
  "arguments": {}
}

返回结果：

{
  "success": true,
  "message": "Schema description generated",
  "schema": {
    "ftk5Tx": "员工",
    "f04Gwj": "客户名称",
    "ftawan": "客户电话",
    "ftQMc5": "单选",
    "ffFwIh": "金额",
    "fn8TJd": "添加客户时间",
    "fo3Koj": "结单时间"
  },
  "description": "字段 ID: ftk5Tx -> 名称: 员工\n字段 ID: f04Gwj -> 名称: 客户名称\n字段 ID: ftawan -> 名称: 客户电话\n字段 ID: ftQMc5 -> 名称: 单选\n字段 ID: ffFwIh -> 名称: 金额\n字段 ID: fn8TJd -> 名称: 添加客户时间\n字段 ID: fo3Koj -> 名称: 结单时间"
}

4. 获取字段详细信息（推荐 AI 使用）

获取详细的字段定义，包括字段类型、是否必填、可选值等。这个工具帮助 AI 更好地理解字段要求：

{
  "name": "get_smartsheet_fields",
  "arguments": {}
}

返回结果：

{
  "success": true,
  "message": "Field definitions retrieved successfully",
  "count": 7,
  "fields": [
    {
      "fieldId": "ftk5Tx",
      "fieldName": "员工",
      "fieldType": "FIELD_TYPE_USER",
      "required": true,
      "description": "负责该客户的员工"
    },
    {
      "fieldId": "f04Gwj",
      "fieldName": "客户名称",
      "fieldType": "FIELD_TYPE_TEXT",
      "required": true,
      "description": "客户的公司或个人名称"
    },
    {
      "fieldId": "ftawan",
      "fieldName": "客户电话",
      "fieldType": "FIELD_TYPE_PHONE_NUMBER",
      "required": false,
      "description": "客户联系电话"
    },
    {
      "fieldId": "ftQMc5",
      "fieldName": "单选",
      "fieldType": "FIELD_TYPE_SINGLE_SELECT",
      "required": false,
      "options": ["未结单", "已结单", "跟进中"],
      "description": "订单状态"
    },
    {
      "fieldId": "ffFwIh",
      "fieldName": "金额",
      "fieldType": "FIELD_TYPE_CURRENCY",
      "required": false,
      "description": "订单金额"
    },
    {
      "fieldId": "fn8TJd",
      "fieldName": "添加客户时间",
      "fieldType": "FIELD_TYPE_DATE_TIME",
      "required": false,
      "description": "客户添加时间"
    },
    {
      "fieldId": "fo3Koj",
      "fieldName": "结单时间",
      "fieldType": "FIELD_TYPE_DATE_TIME",
      "required": false,
      "description": "订单结单时间"
    }
  ]
}

AI 使用建议：

当 AI 模型调用此工具时，它会获得完整的字段信息，包括：

字段 ID 和名称
字段类型（文本、数字、日期、单选等）
是否必填
可选值（单选/多选字段）
字段描述

这样 AI 可以：

✅ 知道应该填写哪些字段
✅ 了解每个字段的类型和格式要求
✅ 知道哪些字段是必填的
✅ 知道单选/多选字段的可用选项
✅ 根据字段描述提供更准确的数据

字段类型支持

文本字段 (FIELD_TYPE_TEXT)

简单模式：

{
  "f04Gwj": "测试文本"
}

完整模式：

{
  "f04Gwj": [
    {
      "type": "text",
      "text": "测试文本"
    }
  ]
}

带链接的文本：

{
  "f04Gwj": [
    {
      "type": "url",
      "text": "企业微信开发者中心",
      "link": "https://developer.work.weixin.qq.com"
    }
  ]
}

数字字段 (FIELD_TYPE_NUMBER)

{
  "ffFwIh": 10
}

复选框字段 (FIELD_TYPE_CHECKBOX)

{
  "ftk5Tx": true
}

日期字段 (FIELD_TYPE_DATE_TIME)

使用毫秒级 Unix 时间戳：

{
  "fn8TJd": 1735660800000
}

图片字段 (FIELD_TYPE_IMAGE)

{
  "图片": [
    {
      "title": "图片标题",
      "image_base64": "base64编码的图片内容"
    }
  ]
}

人员字段 (FIELD_TYPE_USER)

User ID 模式：

{
  "ftk5Tx": [
    {
      "user_id": "USERID1"
    }
  ]
}

链接字段 (FIELD_TYPE_URL)

{
  "链接": [
    {
      "text": "企业微信开发者中心",
      "link": "https://developer.work.weixin.qq.com"
    }
  ]
}

单选字段 (FIELD_TYPE_SINGLE_SELECT)

{
  "ftQMc5": [
    {
      "text": "未结单"
    }
  ]
}

多选字段 (FIELD_TYPE_SELECT)

{
  "标签": [
    {
      "text": "重要"
    },
    {
      "text": "紧急"
    }
  ]
}

进度字段 (FIELD_TYPE_PROGRESS)

{
  "进度": 0.75
}

电话字段 (FIELD_TYPE_PHONE_NUMBER)

{
  "ftawan": "13800138000"
}

邮箱字段 (FIELD_TYPE_EMAIL)

{
  "邮箱": "[email protected]"
}

地理位置字段 (FIELD_TYPE_LOCATION)

{
  "位置": [
    {
      "id": "14313005936863363130",
      "latitude": "23.10647",
      "longitude": "113.32446",
      "source_type": 1,
      "title": "广州塔"
    }
  ]
}

货币字段 (FIELD_TYPE_CURRENCY)

{
  "ffFwIh": 1234.56
}

百分数字段 (FIELD_TYPE_PERCENTAGE)

{
  "完成率": 0.85
}

条码字段 (FIELD_TYPE_BARCODE)

{
  "条码": "1234567890"
}

批量操作

批量添加记录

{
  "name": "add_smartsheet_record",
  "arguments": {
    "records": [
      {
        "values": {
          "ftk5Tx": "张三",
          "f04Gwj": "ABC公司"
        }
      },
      {
        "values": {
          "ftk5Tx": "李四",
          "f04Gwj": "XYZ公司"
        }
      }
    ]
  }
}

限制说明

根据企业微信官方文档，以下字段类型暂不支持通过 Webhook 添加：

公式字段
自动编号字段
查找引用字段
关联字段
创建人字段
创建时间字段
最后编辑人字段
最后编辑时间字段
群聊字段
文件字段

重要限制：

⚠️ 仅支持添加记录：Webhook 接口仅支持添加记录，不支持更新记录
⚠️ 必须使用字段 ID：添加记录时必须使用智能表格的字段 ID，不能使用字段名称
⚠️ 需要配置 Schema：必须在环境变量中配置字段 ID 与字段名称的映射关系
⚠️ 更新功能限制：更新记录功能需要使用企业微信内部接口，需要 access_token，当前版本由于无法接入获取 access_token 的流程，暂不支持更新功能

开发

运行开发模式

npm run dev

构建

npm run build

项目结构

mcp-server/
├── src/
│   ├── index.ts              # MCP 服务器入口
│   ├── wecom-client.ts       # 企业微信 Webhook 客户端
│   └── wecom-smart-client.ts # 智能解析客户端
├── package.json
├── tsconfig.json
├── .env.example
└── README.md

注意事项

Webhook URL 安全：请妥善保管 Webhook URL，不要泄露给他人
字段 ID 必须正确：必须使用智能表格的字段 ID，不能使用字段名称
Schema 配置：必须在环境变量中配置字段 ID 与字段名称的映射关系
单表限制：单个工作表最多支持 100,000 行记录和 15,000,000 个单元格
错误处理：所有 API 调用都有错误处理，会返回详细的错误信息
批量限制：每次最多添加 100 条记录

故障排查

添加记录失败

检查 Webhook URL 是否正确且完整
确认智能表格已开启「接收外部数据」功能
确认字段 ID 与智能表格中的字段 ID 完全一致
确认字段类型与智能表格中的字段类型匹配
检查是否尝试操作不支持的字段类型
确认已正确配置 Schema 环境变量

智能添加记录失败

确认已正确配置 Schema 环境变量
检查输入数据格式是否包含字段名称
确认字段名称与 Schema 中的名称匹配
查看返回的警告信息，了解哪些字段未能解析

Schema 解析失败

确认 WECOM_SMARTSHEET_SCHEMA 是有效的 JSON 格式
检查 JSON 中的键值对格式是否正确
确认字段 ID 和字段名称都是字符串类型

MCP 配置问题

检查 JSON 格式是否正确，注意转义双引号
确认 Webhook URL 是完整的，包含 key 参数
检查 Schema JSON 是否有效，可以使用在线 JSON 验证工具
查看 MCP 客户端日志，确认服务器启动成功
尝试使用 describe_smartsheet_schema 工具测试配置

服务器无法启动

检查 command 和 args 配置是否正确
确认已正确安装依赖（如果是本地运行）
查看服务器日志，确认是否有错误信息
确认 Node.js 版本符合要求（建议 v18 或更高）

许可证

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

WeChat Work (WeCom) SmartSheet MCP Server

功能特性

⚠️ 重要限制

为什么不支持更新记录？

前置要求

安装

方式 1: 从源码安装

方式 2: 使用 npm 全局安装（推荐）

方式 3: 使用 npx（无需安装）

配置

获取 Webhook URL

获取字段 ID 和配置 Schema

格式 1：简单格式（仅包含字段 ID 和名称）

格式 2：详细格式（包含字段类型、是否必填、选项等）

配置环境变量

MCP 配置

完整配置示例

方式 1: 使用 npx（推荐，无需安装）

方式 2: 全局安装后使用

方式 3: 从源码运行

配置参数说明

配置注意事项

配置验证

使用方法

启动服务器

MCP 工具

1. 添加记录（使用字段 ID）

2. 智能添加记录（使用自然语言）

3. 查看字段 Schema

4. 获取字段详细信息（推荐 AI 使用）

字段类型支持

文本字段 (FIELD_TYPE_TEXT)

数字字段 (FIELD_TYPE_NUMBER)

复选框字段 (FIELD_TYPE_CHECKBOX)

日期字段 (FIELD_TYPE_DATE_TIME)

图片字段 (FIELD_TYPE_IMAGE)

人员字段 (FIELD_TYPE_USER)

链接字段 (FIELD_TYPE_URL)

单选字段 (FIELD_TYPE_SINGLE_SELECT)

多选字段 (FIELD_TYPE_SELECT)

进度字段 (FIELD_TYPE_PROGRESS)

电话字段 (FIELD_TYPE_PHONE_NUMBER)

邮箱字段 (FIELD_TYPE_EMAIL)

地理位置字段 (FIELD_TYPE_LOCATION)

货币字段 (FIELD_TYPE_CURRENCY)

百分数字段 (FIELD_TYPE_PERCENTAGE)

条码字段 (FIELD_TYPE_BARCODE)

批量操作

批量添加记录

限制说明

开发

运行开发模式

构建

项目结构

注意事项

故障排查

添加记录失败

智能添加记录失败

Schema 解析失败

MCP 配置问题

服务器无法启动

相关文档

许可证