SuperAPI AI Directory

wecom-smartsheet

General & other

View repository

Updated 10-16 10:22

About this skill

WeCom Smart Sheet Management

wecom_mcp is an MCP tool; all operations are completed by calling this tool.

⚠️ Prerequisite: Before the first call to wecom_mcp , you must follow the wecom-preflight skill 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_mcp tool to call wecom_mcp call doc smartsheet_get_records '{"docid": "DOCID", "sheet_id": "SHEETID"}'
  • or via URL: use the wecom_mcp tool to call wecom_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 call upload_doc_image、upload_doc_file or 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 the image_path / file_path method 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: 851003 or errmsg contains no 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 title
  • CELL_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 call upload_doc_image、upload_doc_file or 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 the image_path / file_path method 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: 851003 or errmsg contains no 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

  1. Understand sheet structure → Use wecom_mcp tool to call wecom_mcp call doc smartsheet_get_sheet → Use wecom_mcp tool to call wecom_mcp call doc smartsheet_get_fields
  2. Create sheet structure → smartsheet_add_sheet Add sub-sheet → smartsheet_add_fields Define columns
  3. Modify sheet structure → smartsheet_update_fields Rename column / smartsheet_delete_fields Delete column

Smart sheet data operations

  1. Read data → Use wecom_mcp tool to call wecom_mcp call doc smartsheet_get_records '{"docid":"DOCID","sheet_id":"SHEETID"}'
  2. Write data → First smartsheet_get_fields understand column types → If a member (USER) field is involved, first use wecom-contact 's get_userlist to look up the person's userid → smartsheet_add_records write
  3. Update data → First smartsheet_get_records get record_id → If a member (USER) field is involved, first use wecom-contact 's get_userlist to look up the person's userid → smartsheet_update_records update
  4. 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
  5. 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 call upload_doc_image、upload_doc_file or 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。
  6. Delete data → First smartsheet_get_records confirm record_id → smartsheet_delete_records delete

Note: Member (USER) type fields require filling in user_id, and names cannot be used directly. You must first use the wecom-contact-lookup skill's get_userlist interface to look up the corresponding userid by 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 call upload_doc_image、upload_doc_file or 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。