Smartsheet MCP 服务器使用说明

项目简介

Smartsheet MCP 服务器是一个基于 Model Context Protocol (MCP) 构建的后端应用，旨在为大型语言模型 (LLM) 客户端提供与 Smartsheet 集成的能力。该服务器充当 AI 系统和 Smartsheet 平台之间的桥梁，通过标准化的 MCP 协议，使得 AI 应用能够安全、可扩展地访问和操作 Smartsheet 数据，并利用专门为医疗健康领域设计的分析工具。

主要功能点

智能集成 Smartsheet: 无缝连接 AI 系统与 Smartsheet 强大的协作平台，实现数据交互和自动化工作流程。
数据操作: 提供全面的 Smartsheet 数据操作工具，包括读取列信息、写入、更新、删除行数据，以及执行条件批量更新。
列管理: 支持动态管理 Smartsheet 表格的列，包括添加、删除和重命名列，并能处理公式和依赖关系。
医疗健康分析: 内置针对医疗健康数据的专业分析工具，例如临床研究分析、医院运营分析和创新评估等。
批量处理: 高效处理大规模医疗健康数据集，支持批量数据更新和分析任务。
灵活配置: 支持多种列类型和复杂数据结构，能够适应不同的 Smartsheet 使用场景。
错误处理: 具备完善的错误处理机制，确保数据操作的稳定性和可靠性。

安装步骤

环境准备:
- 确保已安装 Node.js 和 npm。
- 确保已安装 Conda 用于环境管理。
- 拥有 Smartsheet API 访问令牌。

创建 Conda 环境: 打开终端或命令提示符，创建并激活一个新的 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 服务器需要配置到 MCP 客户端中才能使用，例如 Claude Desktop 或 Cline。以 Cline 为例，配置步骤如下（Claude Desktop 配置类似）：

获取 Smartsheet API 密钥:
- 登录 Smartsheet。
- 进入 "账户" -> "个人设置" -> "API 访问"。
- 生成新的访问令牌。

配置 Cline MCP 设置: 打开 Cline 的 MCP 配置文件 'cline_mcp_settings.json'，文件路径根据操作系统有所不同：

macOS: '~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json'
Windows: '%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'

将以下 JSON 配置添加到 'mcpServers' 字段中。请根据实际情况修改 'command', 'args', 'env' 中的路径和 API 密钥：

{
  "mcpServers": {
    "smartsheet": {
      "command": "/Users/[username]/anaconda3/envs/cline_mcp_env/bin/node", // 替换为你的 Node.js 路径
      "args": ["/path/to/smartsheet-server/build/index.js"], // 替换为你的 smartsheet-server 项目路径
      "env": {
        "PYTHON_PATH": "/Users/[username]/anaconda3/envs/cline_mcp_env/bin/python3", // 替换为你的 Python 路径
        "SMARTSHEET_API_KEY": "your-api-key", // 替换为你的 Smartsheet API 密钥
        "AZURE_OPENAI_API_KEY": "your-azure-openai-key", // 替换为你的 Azure OpenAI API 密钥 (如果需要用到分析功能)
        "AZURE_OPENAI_API_BASE": "your-azure-openai-endpoint", // 替换为你的 Azure OpenAI API Endpoint (如果需要用到分析功能)
        "AZURE_OPENAI_API_VERSION": "your-api-version", // 替换为你的 Azure OpenAI API 版本 (如果需要用到分析功能)
        "AZURE_OPENAI_DEPLOYMENT": "your-deployment-name" // 替换为你的 Azure OpenAI 部署名称 (如果需要用到分析功能)
      },
      "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"
      ]
    }
  }
}

注意:

请将 'command'、'args' 和 'env.PYTHON_PATH' 中的路径替换为你的实际环境路径。
将 'env.SMARTSHEET_API_KEY' 替换为你从 Smartsheet 获取的 API 密钥。
'AZURE_OPENAI_API_KEY', 'AZURE_OPENAI_API_BASE', 'AZURE_OPENAI_API_VERSION', 'AZURE_OPENAI_DEPLOYMENT' 是 Azure OpenAI 相关的配置，如果不需要使用分析功能，可以暂时保留占位符或移除。

基本使用方法

配置完成后，在 Cline 或 Claude Desktop 中，即可通过 '@smartsheet' 服务调用工具与 Smartsheet 进行交互。

示例 1: 获取列信息

// 获取 Smartsheet 表格的列映射和示例数据
const result = await use_mcp_tool({
  server_name: "smartsheet",
  tool_name: "get_column_map",
  arguments: {
    sheet_id: "your-sheet-id", // 替换为你的 Smartsheet 表格 ID
  },
});
console.log(result);

示例 2: 写入数据

// 向 Smartsheet 表格写入新数据
const result = await use_mcp_tool({
  server_name: "smartsheet",
  tool_name: "smartsheet_write",
  arguments: {
    sheet_id: "your-sheet-id", // 替换为你的 Smartsheet 表格 ID
    column_map: { // 列名到列 ID 的映射，可以使用 get_column_map 工具获取
      "Column 1": "1234567890",
      "Column 2": "0987654321",
    },
    row_data: [ // 要写入的行数据
      {
        "Column 1": "Value 1",
        "Column 2": "Value 2",
      },
    ],
  },
});
console.log(result);

更多工具的使用方法，请参考仓库 README.md 中的 "Usage Examples" 部分。

验证安装:

启动服务器后，应输出 "Smartsheet MCP server running on stdio"。
在 Cline 或 Claude Desktop 中，尝试调用 'get_column_map' 工具测试连接。
检查 Python 环境是否已安装 'smartsheet-python-sdk' 包。

通过以上步骤，即可开始使用 Smartsheet MCP 服务器，利用 AI 能力自动化 Smartsheet 的数据操作和分析任务。

关键词