Smartsheet MCP Server

一个用于与Smartsheet API交互的模型上下文协议（MCP）服务器。此服务器提供了通过MCP协议搜索、检索和更新Smartsheet工作表的工具。

目录

• 免责声明
• 特性
• 安装
• 使用
• 可用的MCP工具
• API端点覆盖
• 示例用法
• 环境变量
• 开发
• 贡献

免责声明

MCP是一项新技术。此集成依赖于一个SMARTSHEET API令牌以允许访问您的账户。虽然功能强大，但在处理不受信任的数据时可能会受到提示注入的影响。我们建议谨慎行事，并审查通过这些客户端执行的操作，确保安全运行。

特性

• 获取Smartsheet工作表的详细信息
• 创建、更新和删除工作表及行
• 在特定时间戳创建工作表的版本备份
• 优化供AI消费的格式化响应

安装

1. 克隆仓库：

   git clone https://github.com/smartsheet-platform/smar-mcp.git
   cd smar-mcp
   

2. 安装依赖项：

   npm install
   

3. 在项目根目录创建一个.env文件并添加您的Smartsheet API令牌：

   SMARTSHEET_API_KEY=your_smartsheet_api_token
   

   您可以在Smartsheet开发者门户获取Smartsheet API令牌。

4. 构建项目：

   npm run build
   

使用

有几种方法可以加载.env文件来运行MCP服务器：

使用npm脚本（推荐）

启动服务器并从.env文件加载环境变量：

npm run start

这使用了-r dotenv/config标志，确保在应用代码运行之前加载dotenv。

或者在一条命令中构建并启动：

npm run dev

直接使用Node

您也可以直接使用Node.js和-r标志运行服务器：

node -r dotenv/config build/index.js

这确保在应用代码运行之前加载dotenv。

或者不使用-r标志：

node build/index.js

在这种情况下，应用代码会自行加载dotenv（我们在入口文件顶部包含了import { config } from "dotenv"; config();）。

服务器将启动并显示："Smartsheet MCP Server正在stdio上运行"

可用的MCP工具

get_sheet

检索工作表的当前状态，包括行、列和单元格。

参数：

• sheetId (字符串，必需)：要检索的工作表ID
• include (字符串，可选)：逗号分隔的元素列表（例如，'format,formulas'）

get_sheet_version

获取工作表的当前版本号。

参数：

• sheetId (字符串，必需)：工作表ID

get_cell_history

检索特定单元格的历史更改记录。

参数：

• sheetId (字符串，必需)：工作表ID
• rowId (字符串，必需)：行ID
• columnId (字符串，必需)：列ID
• include (字符串，可选)：可选参数以包含额外信息
• pageSize (数字，可选)：每页返回的历史条目数
• page (数字，可选)：要返回的页码

update_rows

更新工作表中的行，包括单元格值、格式和公式。

参数：

• sheetId (字符串，必需)：工作表ID
• rows (数组，必需)：要更新的行对象数组

add_rows

向工作表中添加新行。

参数：

• sheetId (字符串，必需)：工作表ID
• rows (数组，必需)：要添加的行对象数组

delete_rows

从工作表中删除行。此工具仅在设置ALLOW_DELETE_TOOLS环境变量为'true'时可用。

参数：

• sheetId (字符串，必需)：工作表ID
• rowIds (数组，必需)：要删除的行ID数组
• ignoreRowsNotFound (布尔值，可选)：如果为true，则未找到行时不抛出错误

get_sheet_location

获取工作表所在的文件夹ID。

参数：

• sheetId (字符串，必需)：工作表ID

copy_sheet

在同一文件夹中复制指定的工作表。

参数：

• sheetId (字符串，必需)：要复制的工作表ID
• destinationName (字符串，必需)：副本工作表名称
• destinationFolderId (字符串，可选)：目标文件夹ID（未指定时与源相同）

create_sheet

创建新的工作表。

参数：

• name (字符串，必需)：新工作表名称
• columns (数组，必需)：列对象数组
• folderId (字符串，可选)：创建工作表的文件夹ID

create_version_backup

根据特定时间戳创建工作表的备份。

参数：

• sheetId (字符串，必需)：源工作表ID
• timestamp (字符串，必需)：用于历史数据的ISO 8601时间戳（例如，'2_25-03-27T13:00:00Z'）
• archiveName (字符串，可选)：存档工作表名称（默认为'原始工作表名称 - 存档YYYY-MM-DD'）
• includeFormulas (布尔值，可选，默认为true)：是否在存档中包含公式
• includeFormatting (布尔值，可选，默认为true)：是否在存档中包含格式
• batchSize (数字，可选，默认为100)：每个批次处理的行数
• maxConcurrentRequests (数字，可选，默认为5)：最大并发API请求数

API端点覆盖

此表概述了Smartsheet API端点，它们是否被SMAR-MCP工具覆盖，以及它们对MCP的适用性。

图例：

• 是：端点适合MCP集成
• 否：端点不适合MCP（例如，二进制数据、流式传输或需要特殊处理）
• 考虑：端点可能适用于MCP但可能存在限制（例如，可能需要分页或过滤的大响应）

API路径	被SMAR-MCP覆盖？	HTTP方法(s)	SMAR-MCP工具(s)	对MCP适用？	不适用/考虑原因
/contacts	否	GET	N/A	考虑	列举操作。响应大小可能变化。考虑分页/过滤器。
/contacts/{contactId}	否	GET	N/A	是	检索特定联系人。
/events	否	GET	N/A	否	事件流。可能大/连续。需要特殊处理。
/favorites	否	GET, POST	N/A	是	管理用户收藏。
/favorites/{favoriteType}	否	GET, POST	N/A	是	按类型管理用户收藏。
/favorites/{favoriteType}/{favoriteId}	否	GET, PUT, DELETE	N/A	是	管理特定用户收藏。
/filteredEvents	否	GET	N/A	考虑	过滤事件流。可能大。需要特殊处理。
/folders/{folderId}	是	GET, PUT, DELETE	get_folder (GET)	是	检索特定文件夹。
/folders/{folderId}/copy	否	POST	N/A	是	复制文件夹。
/folders/{folderId}/folders	是	POST	create_folder (POST)	是	管理子文件夹（创建）。通过get_folder列出。
/folders/{folderId}/move	否	POST	N/A	是	移动文件夹。
/folders/{folderId}/sheets	是	POST	create_sheet (POST带folderId)。通过get_folder列出。	是	管理文件夹内的工作表。
/folders/{folderId}/sheets/import	否	POST	N/A	是	将工作表导入文件夹。
/folders/personal	否	GET	N/A	是	访问个人文件夹（Smartsheet特定，可能是GET /home/folders）。
/groups	否	GET, POST	N/A	考虑	列举操作。响应大小可能变化。
/groups/{groupId}	否	GET, PUT, DELETE	N/A	是	检索特定组。
/groups/{groupId}/members	否	GET, POST	N/A	考虑	列举操作。响应大小可能变化。
/groups/{groupId}/members/{userId}	否	DELETE	N/A	是	管理特定组成员。
/home/folders	否	GET	N/A	是	列出用户的家文件夹。
/imageurls	否	POST	N/A	考虑	生成图像URL。响应大小取决于请求。
/reports	否	GET	N/A	考虑	列举操作。响应大小可能变化。
/reports/{reportId}	否	GET, PUT, DELETE	N/A	是	检索特定报告。
/reports/{reportId}/emails	否	POST	N/A	是	通过电子邮件发送报告。
/reports/{reportId}/publish	否	GET, PUT, DELETE	N/A	是	管理报告发布。
/reports/{reportId}/shares	否	GET, POST	N/A	考虑	列举/管理报告共享。
/reports/{reportId}/shares/{shareId}	否	GET, PUT, DELETE	N/A	是	管理特定报告共享。
/search	否	GET	N/A	考虑	全局搜索。响应大小可能非常大。
/search/sheets/{sheetId}	否	GET	N/A	考虑	在特定工作表内搜索。响应大小可能变化。
/serverinfo	否	GET	N/A	是	检索服务器信息。响应小。
/sheets	是	GET, POST	create_sheet (POST无folderId)。未直接暴露列表。	考虑	列举操作（未作为工具暴露）。响应大小可能非常大。
/sheets/import	否	POST	N/A	是	导入工作表。
/sheets/{sheetId}	是	GET, PUT, DELETE	get_sheet (GET)，get_sheet_location (使用GET)	是	检索特定工作表。响应可能很大。
/sheets/{sheetId}/attachments	否	GET, POST	N/A	考虑	列举/管理附件。涉及二进制数据。
/sheets/{sheetId}/attachments/{attachmentId}	否	GET, DELETE	N/A	考虑	获取/删除特定附件。涉及二进制数据。
/sheets/{sheetId}/attachments/{attachmentId}/versions	否	GET	N/A	考虑	列举附件版本。
/sheets/{sheetId}/automationrules	否	GET, POST	N/A	考虑	列举/管理自动化规则。
/sheets/{sheetId}/automationrules/{automationRuleId}	否	GET, PUT, DELETE	N/A	是	获取/更新/删除特定自动化规则。
/sheets/{sheetId}/columns	否	GET, POST	N/A	考虑	列举/管理列。响应大小取决于工作表复杂度。
/sheets/{sheetId}/columns/{columnId}	否	GET, PUT, DELETE	N/A	是	获取/更新/删除特定列。
/sheets/{sheetId}/comments/{commentId}	否	GET, DELETE	N/A	是	获取/删除特定评论。
/sheets/{sheetId}/comments/{commentId}/attachments	否	GET, POST	N/A	考虑	管理评论的附件。涉及二进制数据。
/sheets/{sheetId}/copy	是	POST	copy_sheet (POST)	是	复制工作表。
/sheets/{sheetId}/crosssheetreferences	否	GET, POST	N/A	考虑	列举/管理跨工作表引用。
/sheets/{sheetId}/crosssheetreferences/{crossSheetReferenceId}	否	GET, DELETE	N/A	是	获取/删除特定跨工作表引用。
/sheets/{sheetId}/discussions	是	GET, POST	get_sheet_discussions (GET)	考虑	列举讨论。响应大小可能变化。
/sheets/{sheetId}/discussions/{discussionId}	否	GET, DELETE	N/A	是	获取/删除特定讨论。
/sheets/{sheetId}/discussions/{discussionId}/attachments	否	GET, POST	N/A	考虑	管理讨论的附件。涉及二进制数据。
/sheets/{sheetId}/discussions/{discussionId}/comments	否	GET, POST	N/A	考虑	列举/添加讨论的评论。
/sheets/{sheetId}/emails	否	POST	N/A	是	通过电子邮件发送工作表。
/sheets/{sheetId}/move	否	POST	N/A	是	移动工作表。
/sheets/{sheetId}/proofs	否	GET, POST	N/A	考虑	列举/管理证明。
/sheets/{sheetId}/proofs/{proofId}	否	GET, PUT	N/A	是	获取/更新特定证明。
/sheets/{sheetId}/proofs/{proofId}/attachments	否	GET, POST	N/A	考虑	管理证明的附件。涉及二进制数据。
/sheets/{sheetId}/proofs/{proofId}/discussions	否	GET, POST	N/A	考虑	管理证明的讨论。
/sheets/{sheetId}/proofs/{proofId}/requestactions	否	POST	N/A	是	管理证明的请求动作。
/sheets/{sheetId}/proofs/{proofId}/requests	否	GET, POST	N/A	考虑	管理证明的请求。
/sheets/{sheetId}/proofs/{proofId}/versions	否	GET	N/A	考虑	列举证明的版本。
/sheets/{sheetId}/publish	否	GET, PUT, DELETE	N/A	是	管理工作表发布。
/sheets/{sheetId}/rows	是	GET, POST, PUT, DELETE	update_rows (PUT)，add_rows (POST)，delete_rows (DELETE)	是	管理行。单独行操作没问题。批量操作可能很大。
/sheets/{sheetId}/rows/copy	否	POST	N/A	是	在工作表之间或内部复制行。
/sheets/{sheetId}/rows/emails	否	POST	N/A	是	通过电子邮件发送行。
/sheets/{sheetId}/rows/move	否	POST	N/A	是	在工作表之间或内部移动行。
`/sheets/{sheetId}/