Smartsheet MCP 服务器

模型上下文协议 (MCP) 服务器可与 Smartsheet 无缝集成，并通过标准化接口实现对 Smartsheet 文档的自动化操作。该服务器弥合了 AI 驱动的自动化工具与 Smartsheet 强大的协作平台之间的差距。

概述

Smartsheet MCP 服务器旨在促进与 Smartsheet 的智能交互，提供一套强大的工具用于文档管理、数据操作和列自定义。它是自动化工作流程中的关键组件，使 AI 系统能够以编程方式与 Smartsheet 数据交互，同时保持数据完整性并执行业务规则。

主要优点

智能集成：无缝连接AI系统与Smartsheet协作平台
数据完整性：执行验证规则并维护跨操作的参照完整性
公式管理：自动保存和更新公式参考
灵活配置：支持各种列类型和复杂的数据结构
错误恢复：在多个层面实施全面的错误处理和验证
医疗分析：针对临床和研究数据的专业分析能力
批处理：高效处理大型医疗数据集
自定义评分：针对医疗保健计划和研究的灵活评分系统

用例

临床研究分析
- 协议合规性评分
- 患者数据分析
- 研究影响评估
- 临床试验数据处理
- 自动研究笔记摘要
医院运营
- 资源利用率分析
- 患者满意度评分
- 部门效率指标
- 员工绩效分析
- 质量指标跟踪
医疗保健创新
- 儿科矫正评分
- 创新影响评估
- 研究优先级
- 实施可行性分析
- 临床价值评估
自动化文档管理
- 程序化表单结构修改
- 动态列创建和管理
- 自动数据验证和格式化
数据操作
- 带有完整性检查的批量数据更新
- 智能重复检测
- 公式感知修改
系统集成
- AI驱动的表格定制
- 自动化报告工作流程
- 跨系统数据同步

集成点

该服务器集成了：

用于数据操作的 Smartsheet API
用于标准化通信的 MCP 协议
通过 stdio 接口的本地开发工具
通过结构化日志监控系统

Related MCP server: Google Drive MCP Server

建筑学

服务器实现了 MCP 和 Smartsheet 之间的桥接架构：

graph LR subgraph MCP[MCP Layer] direction TB A[Client Request] --> B[TypeScript MCP Server] B --> C[Tool Registry] B --> D[Config Management] end subgraph CLI[CLI Layer] direction TB E[Python CLI] --> F[Argument Parser] F --> G[Command Router] G --> H[JSON Formatter] end subgraph Core[Core Operations] direction TB I[Smartsheet API Client] --> J[Column Manager] J --> K[Data Validator] J --> L[Formula Parser] end MCP --> CLI --> Core style A fill:#f9f,stroke:#333 style I fill:#bbf,stroke:#333

TypeScript MCP 层（ src/index.ts ）
- 处理 MCP 协议通信
- 注册并管理可用工具
- 将请求路由到 Python 实现
- 管理配置和错误处理
Python CLI 层（ smartsheet_ops/cli.py ）
- 提供命令行操作界面
- 处理参数解析和验证
- 实现重复检测
- 管理 JSON 数据格式
核心操作层（ smartsheet_ops/__init__.py ）
- 实现 Smartsheet API 交互
- 处理复杂的列类型管理
- 提供数据规范化和验证
- 管理系统列和公式解析

列管理流程

sequenceDiagram participant C as Client participant M as MCP Server participant P as Python CLI participant S as Smartsheet API C->>M: Column Operation Request M->>P: Parse & Validate Request alt Add Column P->>S: Validate Column Limit S-->>P: Sheet Info P->>S: Create Column S-->>P: Column Created P->>S: Get Column Details S-->>P: Column Info else Delete Column P->>S: Check Dependencies S-->>P: Formula References alt Has Dependencies P-->>M: Dependency Error M-->>C: Cannot Delete else No Dependencies P->>S: Delete Column S-->>P: Success end else Rename Column P->>S: Check Name Uniqueness S-->>P: Validation Result P->>S: Update Column Name S-->>P: Name Updated P->>S: Update Formula References S-->>P: References Updated end P-->>M: Operation Result M-->>C: Formatted Response

错误处理流程

flowchart TD A[Client Request] --> B{MCP Layer} B -->|Validation Error| C[Return Error Response] B -->|Valid Request| D{CLI Layer} D -->|Parse Error| E[Format JSON Error] D -->|Valid Command| F{Core Operations} F -->|API Error| G[Handle API Exception] F -->|Validation Error| H[Check Error Type] F -->|Success| I[Format Success Response] H -->|Dependencies| J[Return Dependency Info] H -->|Limits| K[Return Limit Error] H -->|Data| L[Return Validation Details] G --> M[Format Error Response] J --> N[Send to Client] K --> N L --> N I --> N style A fill:#f9f,stroke:#333 style N fill:#bbf,stroke:#333

特征

工具

get_column_map （读取）
- 从 Smartsheet 中检索列映射和示例数据
- 提供详细的列元数据，包括：
  - 列类型（系统列、公式、选择列表）
  - 验证规则
  - 格式规范
  - 自动编号配置
- 返回上下文的示例数据
- 包含写入数据的使用示例
smartsheet_write （创建）
- 通过智能处理将新行写入 Smartsheet：
  - 系统管理的列
  - 多选选项列表值
  - 基于公式的列
- 实现自动重复检测
- 返回包括行ID在内的详细操作结果
smartsheet_update （更新）
- 更新 Smartsheet 中的现有行
- 支持部分更新（修改特定字段）
- 通过验证维护数据完整性
- 一致地处理多选字段
- 返回每行的成功/失败详细信息
smartsheet_delete （删除）
- 从 Smartsheet 中删除行
- 支持批量删除多行
- 验证行存在和权限
- 返回详细操作结果
smartsheet_add_column （列管理）
- 向 Smartsheet 添加新列
- 支持所有列类型：
  - 文本号码
  - 日期
  - 复选框
  - 选择列表
  - 联系人列表
- 可配置选项：
  - 位置索引
  - 验证规则
  - 公式定义
  - 选择列表选项
- 通过验证强制执行列限制（400）
- 返回详细的列信息
smartsheet_delete_column （列管理）
- 通过依赖性检查安全地删除列
- 删除前验证公式引用
- 防止删除公式中使用的列
- 返回详细的依赖信息
- 支持强制删除选项
smartsheet_rename_column （列管理）
- 重命名列同时保留关系
- 自动更新公式引用
- 维护数据完整性
- 验证名称唯一性
- 返回详细的更新信息
smartsheet_bulk_update （有条件更新）
- 根据规则执行有条件的批量更新
- 支持复杂条件评估：
  - 多个运算符（等于、包含、大于等）
  - 特定类型的比较（文本、日期、数字）
  - 空/非空检查
- 可配置大小的批处理
- 全面的错误处理和回滚
- 详细的运营结果追踪
start_batch_analysis （医疗分析）
- 使用 AI 分析处理整个工作表或选定的行
- 支持多种分析类型：
  - 临床记录总结
  - 患者反馈的情绪分析
  - 医疗保健计划的定制评分
  - 研究影响评估
- 特征：
  - 自动批处理（每批50行）
  - 进度跟踪和状态监控
  - 错误处理及详细报告
  - 可定制的分析目标
  - 支持多个源列
get_job_status （分析监控）

跟踪批量分析进度
提供详细的工作统计数据：
- 要处理的总行数
- 已处理行数
- 失败行数
- 处理时间戳
实时状态更新
全面的错误报告

cancel_batch_analysis （作业控制）

取消正在运行的批量分析作业
优雅终止进程
保持数据一致性
返回最终作业状态

关键功能

列类型管理
- 处理系统列类型（AUTO_NUMBER、CREATED_DATE 等）
- 支持公式解析和依赖关系跟踪
- 管理选择列表选项和多选值
- 全面的列操作（添加、删除、重命名）
- 公式参考保存和更新
数据验证
- 自动重复检测
- 列类型验证
- 数据格式验证
- 列依赖性分析
- 名称唯一性验证
元数据处理
- 提取并处理列元数据
- 处理验证规则
- 管理格式规范
- 跟踪公式依赖关系
- 维护列关系
医疗保健分析
- 临床记录总结
- 患者反馈情绪分析
- 协议合规性评分
- 研究影响评估
- 资源利用率分析
批处理
- 自动行分批（每批50行）
- 进度跟踪和监控
- 错误处理和恢复
- 可定制的处理目标
- 多列分析支持
作业管理
- 实时状态监控
- 详细进度追踪
- 错误报告和日志记录
- 作业取消支持
- 批量操作控制

设置

先决条件

Node.js 和 npm
Conda（用于环境管理）
Smartsheet API 访问令牌

环境设置

创建专用的 conda 环境：

conda create -n cline_mcp_env python=3.12 nodejs -y conda activate cline_mcp_env

安装 Node.js 依赖项：

npm install

安装 Python 包：

cd smartsheet_ops pip install -e . cd ..

构建 TypeScript 服务器：

npm run build

配置

该服务器需要您在 MCP 设置中进行适当的配置。您可以将其与 Claude Desktop 和 Cline 一起使用。

1. 获取您的 Smartsheet API 密钥

登录Smartsheet
前往账户 → 个人设置 → API 访问
生成新的访问令牌

2. 配置 Cline

配置路径取决于您的操作系统：

macOS 系统：

~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

窗户：

%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json

Linux ：

~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

{ "mcpServers": { "smartsheet": { "command": "/Users/[username]/anaconda3/envs/cline_mcp_env/bin/node", "args": ["/path/to/smartsheet-server/build/index.js"], "env": { "PYTHON_PATH": "/Users/[username]/anaconda3/envs/cline_mcp_env/bin/python3", "SMARTSHEET_API_KEY": "your-api-key", "AZURE_OPENAI_API_KEY": "your-azure-openai-key", "AZURE_OPENAI_API_BASE": "your-azure-openai-endpoint", "AZURE_OPENAI_API_VERSION": "your-api-version", "AZURE_OPENAI_DEPLOYMENT": "your-deployment-name" }, "disabled": false, "autoApprove": [ "get_column_map", "smartsheet_write", "smartsheet_update", "smartsheet_delete", "smartsheet_search", "smartsheet_add_column", "smartsheet_delete_column", "smartsheet_rename_column", "smartsheet_bulk_update", "start_batch_analysis", "get_job_status", "cancel_batch_analysis" ] } } }

3. 配置 Claude Desktop（可选）

配置路径取决于您的操作系统：

macOS 系统：

~/Library/Application Support/Claude/claude_desktop_config.json

窗户：

%APPDATA%\Claude\claude_desktop_config.json

Linux ：

~/.config/Claude/claude_desktop_config.json

启动服务器

当 Cline 或 Claude Desktop 需要时，服务器会自动启动。当然，您也可以手动启动它进行测试。

macOS/Linux ：

# Activate the environment conda activate cline_mcp_env # Start the server PYTHON_PATH=/Users/[username]/anaconda3/envs/cline_mcp_env/bin/python3 SMARTSHEET_API_KEY=your-api-key node build/index.js

窗户：

:: Activate the environment conda activate cline_mcp_env :: Start the server set PYTHON_PATH=C:\Users\[username]\anaconda3\envs\cline_mcp_env\python.exe set SMARTSHEET_API_KEY=your-api-key node build\index.js

验证安装

服务器启动时应输出“Smartsheet MCP 服务器在 stdio 上运行”
使用任何 MCP 工具（例如 get_column_map）测试连接
检查 Python 环境是否安装了 smartsheet 包：
conda activate cline_mcp_env pip show smartsheet-python-sdk

使用示例

获取列信息（读取）

// Get column mapping and sample data const result = await use_mcp_tool({ server_name: "smartsheet", tool_name: "get_column_map", arguments: { sheet_id: "your-sheet-id", }, });

写入数据（创建）

// Write new rows to Smartsheet const result = await use_mcp_tool({ server_name: "smartsheet", tool_name: "smartsheet_write", arguments: { sheet_id: "your-sheet-id", column_map: { "Column 1": "1234567890", "Column 2": "0987654321", }, row_data: [ { "Column 1": "Value 1", "Column 2": "Value 2", }, ], }, });

更新数据（更新）

// Update existing rows const result = await use_mcp_tool({ server_name: "smartsheet", tool_name: "smartsheet_update", arguments: { sheet_id: "your-sheet-id", column_map: { Status: "850892021780356", Notes: "6861293012340612", }, updates: [ { row_id: "7670198317295492", data: { Status: "In Progress", Notes: "Updated via MCP server", }, }, ], }, });

删除数据（Delete）

// Delete rows from Smartsheet const result = await use_mcp_tool({ server_name: "smartsheet", tool_name: "smartsheet_delete", arguments: { sheet_id: "your-sheet-id", row_ids: ["7670198317295492", "7670198317295493"], }, });

医疗保健分析示例

// Example 1: Pediatric Innovation Scoring const result = await use_mcp_tool({ server_name: "smartsheet", tool_name: "start_batch_analysis", arguments: { sheet_id: "your-sheet-id", type: "custom", sourceColumns: ["Ideas", "Implementation_Details"], targetColumn: "Pediatric_Score", customGoal: "Score each innovation 1-100 based on pediatric healthcare impact. Consider: 1) Direct benefit to child patients, 2) Integration with pediatric workflows, 3) Implementation feasibility in children's hospital, 4) Safety considerations for pediatric use. Return only a number.", }, }); // Example 2: Clinical Note Summarization const result = await use_mcp_tool({ server_name: "smartsheet", tool_name: "start_batch_analysis", arguments: { sheet_id: "your-sheet-id", type: "summarize", sourceColumns: ["Clinical_Notes"], targetColumn: "Note_Summary", }, }); // Example 3: Patient Satisfaction Analysis const result = await use_mcp_tool({ server_name: "smartsheet", tool_name: "start_batch_analysis", arguments: { sheet_id: "your-sheet-id", type: "sentiment", sourceColumns: ["Patient_Feedback"], targetColumn: "Satisfaction_Score", }, }); // Example 4: Protocol Compliance Scoring const result = await use_mcp_tool({ server_name: "smartsheet", tool_name: "start_batch_analysis", arguments: { sheet_id: "your-sheet-id", type: "custom", sourceColumns: ["Protocol_Steps", "Documentation", "Outcomes"], targetColumn: "Compliance_Score", customGoal: "Score protocol compliance 1-100. Consider: 1) Adherence to required steps, 2) Documentation completeness, 3) Safety measures followed, 4) Outcome reporting. Return only a number.", }, }); // Example 5: Research Impact Assessment const result = await use_mcp_tool({ server_name: "smartsheet", tool_name: "start_batch_analysis", arguments: { sheet_id: "your-sheet-id", type: "custom", sourceColumns: ["Research_Findings", "Clinical_Applications"], targetColumn: "Impact_Score", customGoal: "Score research impact 1-100 based on potential benefit to pediatric healthcare. Consider: 1) Clinical relevance, 2) Implementation potential, 3) Patient outcome improvement, 4) Cost-effectiveness. Return only a number.", }, }); // Monitor Analysis Progress const status = await use_mcp_tool({ server_name: "smartsheet", tool_name: "get_job_status", arguments: { sheet_id: "your-sheet-id", jobId: "job-id-from-start-analysis", }, }); // Cancel Analysis if Needed const cancel = await use_mcp_tool({ server_name: "smartsheet", tool_name: "cancel_batch_analysis", arguments: { sheet_id: "your-sheet-id", jobId: "job-id-to-cancel", }, });

管理列

// Add a new column const result = await use_mcp_tool({ server_name: "smartsheet", tool_name: "smartsheet_add_column", arguments: { sheet_id: "your-sheet-id", title: "New Column", type: "TEXT_NUMBER", index: 2, // Optional position validation: true, // Optional formula: "=[Column1]+ [Column2]", // Optional }, }); // Delete a column const result = await use_mcp_tool({ server_name: "smartsheet", tool_name: "smartsheet_delete_column", arguments: { sheet_id: "your-sheet-id", column_id: "1234567890", validate_dependencies: true, // Optional, default true }, }); // Rename a column const result = await use_mcp_tool({ server_name: "smartsheet", tool_name: "smartsheet_rename_column", arguments: { sheet_id: "your-sheet-id", column_id: "1234567890", new_title: "Updated Column Name", update_references: true, // Optional, default true }, });

有条件批量更新

smartsheet_bulk_update工具提供了强大的条件更新功能。以下是一些从简单到复杂的示例：

简单条件示例

// Example 1: Basic equals comparison const result = await use_mcp_tool({ server_name: "smartsheet", tool_name: "smartsheet_bulk_update", arguments: { sheet_id: "your-sheet-id", rules: [{ conditions: [{ columnId: "status-column-id", operator: "equals", value: "Pending" }], updates: [{ columnId: "status-column-id", value: "In Progress" }] }] } }); // Example 2: Contains text search const result = await use_mcp_tool({ server_name: "smartsheet", tool_name: "smartsheet_bulk_update", arguments: { sheet_id: "your-sheet-id", rules: [{ conditions: [{ columnId: "description-column-id", operator: "contains", value: "urgent" }], updates: [{ columnId: "priority-column-id", value: "High" }] }] } }); // Example 3: Empty value check const result = await use_mcp_tool({ server_name: "smartsheet", tool_name: "smartsheet_bulk_update", arguments: { sheet_id: "your-sheet-id", rules: [{ conditions: [{ columnId: "assignee-column-id", operator: "isEmpty" }], updates: [{ columnId: "status-column-id", value: "Unassigned" }] }] } });

特定类型的比较

// Example 1: Date comparison const result = await use_mcp_tool({ server_name: "smartsheet", tool_name: "smartsheet_bulk_update", arguments: { sheet_id: "your-sheet-id", rules: [ { conditions: [ { columnId: "due-date-column-id", operator: "lessThan", value: "2025-02-01T00:00:00Z", // ISO date format }, ], updates: [ { columnId: "status-column-id", value: "Due Soon", }, ], }, ], }, }); // Example 2: Numeric comparison const result = await use_mcp_tool({ server_name: "smartsheet", tool_name: "smartsheet_bulk_update", arguments: { sheet_id: "your-sheet-id", rules: [ { conditions: [ { columnId: "progress-column-id", operator: "greaterThan", value: 80, // Numeric value }, ], updates: [ { columnId: "status-column-id", value: "Nearly Complete", }, ], }, ], }, }); // Example 3: Picklist validation const result = await use_mcp_tool({ server_name: "smartsheet", tool_name: "smartsheet_bulk_update", arguments: { sheet_id: "your-sheet-id", rules: [ { conditions: [ { columnId: "category-column-id", operator: "equals", value: "Bug", // Must match picklist option exactly }, ], updates: [ { columnId: "priority-column-id", value: "High", }, ], }, ], }, });

复杂的多条件示例

// Example 1: Multiple conditions with different operators const result = await use_mcp_tool({ server_name: "smartsheet", tool_name: "smartsheet_bulk_update", arguments: { sheet_id: "your-sheet-id", rules: [ { conditions: [ { columnId: "priority-column-id", operator: "equals", value: "High", }, { columnId: "due-date-column-id", operator: "lessThan", value: "2025-02-01T00:00:00Z", }, { columnId: "progress-column-id", operator: "lessThan", value: 50, }, ], updates: [ { columnId: "status-column-id", value: "At Risk", }, { columnId: "flag-column-id", value: true, }, ], }, ], }, }); // Example 2: Multiple rules with batch processing const result = await use_mcp_tool({ server_name: "smartsheet", tool_name: "smartsheet_bulk_update", arguments: { sheet_id: "your-sheet-id", rules: [ { conditions: [ { columnId: "status-column-id", operator: "equals", value: "Complete", }, { columnId: "qa-status-column-id", operator: "isEmpty", }, ], updates: [ { columnId: "qa-status-column-id", value: "Ready for QA", }, ], }, { conditions: [ { columnId: "status-column-id", operator: "equals", value: "In Progress", }, { columnId: "progress-column-id", operator: "equals", value: 100, }, ], updates: [ { columnId: "status-column-id", value: "Complete", }, ], }, ], options: { lenientMode: true, // Continue on errors batchSize: 100, // Process in smaller batches }, }, });

批量更新操作提供：

操作员支持：
- equals ：精确值匹配
- contains ：子字符串匹配
- greaterThan ：数字/日期比较
- lessThan ：数字/日期比较
- isEmpty ：Null/空检查
- isNotEmpty ：当前值检查
特定类型特征：
- TEXT_NUMBER：字符串/数字比较
- DATE：ISO 日期解析和比较
- PICKLIST：选项验证
- CHECKBOX：布尔处理
处理选项：
- batchSize ：控制更新批次大小（默认500）
- lenientMode ：出现错误时继续
- 每个请求有多个规则
- 每条规则有多个更新
结果跟踪：
- 尝试的总行数
- 成功/失败很重要
- 详细错误信息
- 每行故障详细信息

发展

对于使用自动重建的开发：

npm run watch

调试

由于 MCP 服务器通过 stdio 进行通信，因此调试起来可能颇具挑战性。该服务器实现了全面的错误日志记录，并通过 MCP 协议提供详细的错误消息。

主要调试功能：

错误记录到 stderr
MCP 响应中的详细错误消息
多层次的类型验证
全面的运营结果报告
列操作的依赖性分析
配方参考追踪

错误处理

服务器实现了多层错误处理方法：

MCP层
- 验证工具参数
- 处理协议级错误
- 提供格式化的错误响应
- 管理超时和重试
CLI层
- 验证命令参数
- 处理执行错误
- 将错误消息格式化为 JSON
- 验证列操作
操作层
- 处理 Smartsheet API 错误
- 验证数据类型和格式
- 提供详细的错误上下文
- 管理列依赖关系
- 验证公式引用
- 确保数据完整性

贡献

欢迎投稿！请确保：

TypeScript/Python 代码遵循现有风格
新功能包括适当的错误处理
更改保持向后兼容性
更新包括适当的文档
列操作维护数据完整性
公式引用得到妥善处理

Smartsheet MCP Server