A
security-
licenseA
qualityProvides integration with OpenRouter.ai, allowing access to various AI models through a unified interface.
Last updated -
58
61
Apache 2.0
Smartsheet MCP 服务器
模型上下文协议 (MCP) 服务器可与 Smartsheet 无缝集成，并通过标准化接口实现对 Smartsheet 文档的自动化操作。该服务器弥合了 AI 驱动的自动化工具与 Smartsheet 强大的协作平台之间的差距。
概述
Smartsheet MCP 服务器旨在促进与 Smartsheet 的智能交互，提供一套强大的工具用于文档管理、数据操作和列自定义。它是自动化工作流程中的关键组件，使 AI 系统能够以编程方式与 Smartsheet 数据交互，同时保持数据完整性并执行业务规则。
主要优点
智能集成：无缝连接AI系统与Smartsheet协作平台
数据完整性：执行验证规则并维护跨操作的参照完整性
公式管理：自动保存和更新公式参考
灵活配置：支持各种列类型和复杂的数据结构
错误恢复：在多个层面实施全面的错误处理和验证
医疗分析：针对临床和研究数据的专业分析能力
批处理：高效处理大型医疗数据集
自定义评分：针对医疗保健计划和研究的灵活评分系统
用例
临床研究分析
协议合规性评分
患者数据分析
研究影响评估
临床试验数据处理
自动研究笔记摘要
医院运营
资源利用率分析
患者满意度评分
部门效率指标
员工绩效分析
质量指标跟踪
医疗保健创新
儿科矫正评分
创新影响评估
研究优先级
实施可行性分析
临床价值评估
自动化文档管理
程序化表单结构修改
动态列创建和管理
自动数据验证和格式化
数据操作
带有完整性检查的批量数据更新
智能重复检测
公式感知修改
系统集成
AI驱动的表格定制
自动化报告工作流程
跨系统数据同步
集成点
该服务器集成了：
用于数据操作的 Smartsheet API
用于标准化通信的 MCP 协议
通过 stdio 接口的本地开发工具
通过结构化日志监控系统
建筑学
服务器实现了 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 密钥
前往账户 → 个人设置 → 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
{
"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"
]
}
}
}
启动服务器
当 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 代码遵循现有风格
新功能包括适当的错误处理
更改保持向后兼容性
更新包括适当的文档
列操作维护数据完整性
公式引用得到妥善处理
Related MCP Servers
- -security-license-qualityEnables integration with Google Drive for listing, reading, and searching over files, supporting various file types with automatic export for Google Workspace files.Last updated -63452MIT License
- -security-license-qualityIntegrates with Google Drive to enable listing, searching, and reading files, plus reading and writing to Google Sheets.Last updated -196210MIT License
- -security-license-qualityIntegrates with Google Drive to enable listing, reading, and searching over files, with automatic export of Google Workspace documents to appropriate formats.Last updated -634