wecom_mcpis an MCP tool; all operations are completed by calling this tool.
⚠️ Prerequisite: Before the first call to
wecom_mcp, you must follow thewecom-preflightskill to perform the prerequisite check to ensure the tool has been added to the whitelist.
Manage the structure (subsheets, fields/columns) and data (records) of WeCom smart sheets. All APIs support locating the document via either docid or url .
Invocation Method
Call via the wecom_mcp tool; the category name is doc:
Use the wecom_mcp tool to call wecom_mcp call doc <tool_name> '<json_params>' to invoke the specified skill
Return Format Description
All APIs return a JSON object containing the following common fields:
| Field | Type | Description |
|---|---|---|
errcode |
integer | Return code,0 indicates success, non- 0 indicates failure |
errmsg |
string | Error message, which is "ok" |
When errcode is not 0 , it indicates the API call failed, and you can retry once; if it still fails, display errcode and errmsg to the user.
I. Smart Sheet Structure Management
smartsheet_get_sheet
Query information for all subsheets in the document, returning sheet_id, title, type, etc.
Use the wecom_mcp tool to call wecom_mcp call doc smartsheet_get_sheet '{"docid": "DOCID"}'
smartsheet_add_sheet
Add an empty subsheet. The new subsheet contains no views, records, or fields, and must be supplemented through other APIs.
Use the wecom_mcp tool to call wecom_mcp call doc smartsheet_add_sheet '{"docid": "DOCID", "properties": {"title": "新子表"}}'
Note: A newly created smart sheet document already contains one subsheet by default; call this only when multiple subsheets are needed.
smartsheet_update_sheet
Modify the subsheet title. You must provide the sheet_id and the new title.
Use the wecom_mcp tool to call wecom_mcp call doc smartsheet_update_sheet '{"docid": "DOCID", "properties": {"sheet_id": "SHEET_ID", "title": "新子表"}}'
smartsheet_delete_sheet
Permanently delete a subsheet;the operation is irreversible。
Use the wecom_mcp tool to call wecom_mcp call doc smartsheet_delete_sheet '{"docid": "DOCID", "sheet_id": "SHEETID"}'
smartsheet_get_fields
Query all field information of a subsheet, returning field_id, field_title, and field_type.
Use the wecom_mcp tool to call wecom_mcp call doc smartsheet_get_fields '{"docid": "DOCID", "sheet_id": "SHEETID"}'
smartsheet_add_fields
Add one or more fields to a subsheet. A single subsheet supports up to 150 fields.
Use the wecom_mcp tool to call wecom_mcp call doc smartsheet_add_fields '{"docid": "DOCID", "sheet_id": "SHEETID", "fields": [{"field_title": "任务名称", "field_type": "FIELD_TYPE_TEXT"}]}'
Before adding fields, please first refer to all field types and definitions Field Type Reference。
smartsheet_update_fields
Update the field title.Only the name can be changed; the type cannot be changed(field_type must be passed as the original type). field_title cannot be updated to its original value.
Use the wecom_mcp tool to call wecom_mcp call doc smartsheet_update_fields '{"docid": "DOCID", "sheet_id": "SHEETID", "fields": [{"field_id": "FIELDID", "field_title": "新标题", "field_type": "FIELD_TYPE_TEXT"}]}'
smartsheet_delete_fields
Delete one or more columns of fields;the operation is irreversible. field_id can be obtained via smartsheet_get_fields .
Use the wecom_mcp tool to call wecom_mcp call doc smartsheet_delete_fields '{"docid": "DOCID", "sheet_id": "SHEETID", "field_ids": ["FIELDID"]}'
II. Smart Sheet Data Management
smartsheet_get_records
Query all records in a subsheet.
- Via sheetid: use the
wecom_mcptool to callwecom_mcp call doc smartsheet_get_records '{"docid": "DOCID", "sheet_id": "SHEETID"}' - or via URL: use the
wecom_mcptool to callwecom_mcp call doc smartsheet_get_records '{"url": "https://doc.weixin.qq.com/smartsheet/xxx", "sheet_id": "SHEETID"}'
See API Details。
smartsheet_add_records
Add one or more records; a single call is recommended to be within 500 rows.
Before callingYou must first understand the field types of the target sheet (via smartsheet_get_fields), and checkCell value format reference, and only proceed after understanding how to do it.
Use wecom_mcp tool to call wecom_mcp call doc smartsheet_add_records '{"docid": "DOCID", "sheet_id": "SHEETID", "records": [{"values": {"任务名称": [{"type": "text", "text": "完成需求文档"}], "优先级": [{"text": "高"}]}}]}'
For the value formats of each field type, see Cell value format reference。
⚠️ Image (IMAGE) / File (ATTACHMENT) fields:must and can onlypass the local path directly in the cell value (
image_path/file_path); see the examples below for the format.Strictly prohibitedto callupload_doc_image、upload_doc_fileor any upload API,strictly prohibitedto perform base64 encoding—regardless of file size and regardless of what error the API returns, this rule must not be bypassed. If theimage_path/file_pathmethod returns an error, you should directly inform the user of the error code and error message,must nottry other upload methods.Image field example:
"封面": [{"image_path": "/path/to/img.png", "title": "图片标题"}]File field example:"文件": [{"file_path": "/path/to/file.pdf"}]
⚠️ If it returns
errcode: 851003orerrmsgcontainsno authority(usually the enterprise visibility scope > 10 people scale limit), switch to the Webhook fallback solution, see webhook-fallback.md。
smartsheet_update_records
Before callingYou must first understand the field types of the target sheet (via smartsheet_get_fields), and checkCell value format reference, and only proceed after understanding how to do it.
Update one or more records; a single call is recommended to be within 500 rows. You need to provide record_id (obtained via smartsheet_get_records ). Supports specifying via key_type that the key of values uses the field title or field ID:
CELL_VALUE_KEY_TYPE_FIELD_TITLE: key is the field titleCELL_VALUE_KEY_TYPE_FIELD_ID: key is the field ID
Use wecom_mcp tool to call wecom_mcp call doc smartsheet_update_records '{"docid": "DOCID", "sheet_id": "SHEETID", "key_type": "CELL_VALUE_KEY_TYPE_FIELD_ID", "records": [{"record_id": "RECORDID", "values": {"FIELDID": [{"type": "text", "text": "更新后的内容"}]}}]}'
Note: the Created Time, Last Edited Time, Created By, and Last Edited By fields cannot be updated.
⚠️ Image (IMAGE) / File (ATTACHMENT) fields:must and can onlypass the local path directly in the cell value (
image_path/file_path); see the examples below for the format.Strictly prohibitedto callupload_doc_image、upload_doc_fileor any upload API,strictly prohibitedto perform base64 encoding—regardless of file size and regardless of what error the API returns, this rule must not be bypassed. If theimage_path/file_pathmethod returns an error, you should directly inform the user of the error code and error message,must nottry other upload methods.Image field example:
"封面": [{"image_path": "/path/to/img.png", "title": "图片标题"}]File field example:"文件": [{"file_path": "/path/to/file.pdf"}]
⚠️ If it returns
errcode: 851003orerrmsgcontainsno authority(usually the enterprise visibility scope > 10 people scale limit), switch to the Webhook fallback solution, see webhook-fallback.md. Note that Webhook can only update records written via Webhook; manually created records cannot be updated.
smartsheet_delete_records
Delete one or more records; a single call must be within 500 rows.The operation is irreversible. record_id is obtained via smartsheet_get_records .
Use wecom_mcp tool to call wecom_mcp call doc smartsheet_delete_records '{"docid": "DOCID", "sheet_id": "SHEETID", "record_ids": ["RECORDID1", "RECORDID2"]}'
Typical workflow
Smart sheet structure operations
- Understand sheet structure →
Use
wecom_mcptool to callwecom_mcp call doc smartsheet_get_sheet→ Usewecom_mcptool to callwecom_mcp call doc smartsheet_get_fields - Create sheet structure →
smartsheet_add_sheetAdd sub-sheet →smartsheet_add_fieldsDefine columns - Modify sheet structure →
smartsheet_update_fieldsRename column /smartsheet_delete_fieldsDelete column
Smart sheet data operations
- Read data → Use
wecom_mcptool to callwecom_mcp call doc smartsheet_get_records '{"docid":"DOCID","sheet_id":"SHEETID"}' - Write data → First
smartsheet_get_fieldsunderstand column types → If a member (USER) field is involved, first usewecom-contact'sget_userlistto look up the person's userid →smartsheet_add_recordswrite - Update data → First
smartsheet_get_recordsget record_id → If a member (USER) field is involved, first usewecom-contact'sget_userlistto look up the person's userid →smartsheet_update_recordsupdate - Write failure fallback → When step 2/3 returns
errcode: 851003/no authority(usually the enterprise visibility scope > 10 people scale limit) → Ask the user to temporarily provide the target sheet's Webhook address + schema example JSON (not saved locally) → Follow webhook-fallback.md to construct the request body and send - If an **image (IMAGE) or file (ATTACHMENT)** field is involved,must and can onlydirectly pass the local path in the cell value (
image_path/file_path)。strictly forbiddento callupload_doc_image、upload_doc_fileor any upload interface,strictly forbiddento perform base64 encoding—regardless of file size, regardless of what error the API returns, this rule must not be bypassed. If an error is returned, directly inform the user of the error code and error message, and do not attempt any other upload method. For the input format, refer to For the cell value format, refer to。 - Delete data → First
smartsheet_get_recordsconfirm record_id →smartsheet_delete_recordsdelete
Note: Member (USER) type fields require filling in
user_id, and names cannot be used directly. You must first use thewecom-contact-lookupskill'sget_userlistinterface to look up the correspondinguseridby name before using it. Note: Image (IMAGE) or file (ATTACHMENT) fieldsmust and can onlydirectly pass the local path in the cell value (image_path/file_path)。strictly forbiddento callupload_doc_image、upload_doc_fileor any upload interface,strictly forbiddento perform base64 encoding—regardless of file size, regardless of what error the API returns, this rule must not be bypassed. If an error is returned, directly inform the user of the error code and error message, and do not attempt any other upload method. For the format, refer to For the cell value format, refer to。