Smartsheet MCP 服务器

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

概述

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

主要优点

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

用例

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

集成点

该服务器集成了：

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

建筑学

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

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

列管理流程

错误处理流程

特征

工具

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

{
  "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
  },
});

### Conditional Bulk Updates

The `smartsheet_bulk_update` tool provides powerful conditional update capabilities. Here are examples ranging from simple to complex:

#### Simple Condition Examples

```typescript
// 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 ：出现错误时继续
- 每个请求有多个规则
- 每条规则有多个更新
结果跟踪：
- 尝试的总行数
- 成功/失败很重要
- 详细错误信息
- 每行故障详细信息

## Development

For development with auto-rebuild:

```bash
npm run watch

调试

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

主要调试功能：

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

错误处理

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

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

贡献

欢迎投稿！请确保：

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

Smartsheet MCP Server

Integrations