Smartsheet MCP サーバー
Smartsheetとのシームレスな統合を実現するモデルコンテキストプロトコル（MCP）サーバー。標準化されたインターフェースを通じてSmartsheetドキュメントの自動操作を可能にします。このサーバーは、AIを活用した自動化ツールとSmartsheetの強力なコラボレーションプラットフォーム間のギャップを埋めます。
概要
Smartsheet MCP Serverは、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 (条件付き更新)- ルールに基づいて条件付き一括更新を実行します
- 複雑な条件評価をサポートします:
- 複数の演算子 (equals、contains、greaterThan など)
- 型別の比較（テキスト、日付、数値）
- 空/空でない小切手
- 設定可能なサイズでのバッチ処理
- 包括的なエラー処理とロールバック
- 詳細な操作結果の追跡
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 の依存関係をインストールします。
- Python パッケージをインストールします。
cd smartsheet_ops
pip install -e .
cd ..
- TypeScript サーバーを構築します。
構成
サーバーは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
リナックス:
~/.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
リナックス:
~/.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 server running on 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 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日付の解析と比較
- ピックリスト: オプション検証
- チェックボックス: ブール処理
- 処理オプション:
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コードは既存のスタイルに従います
- 新しい機能には適切なエラー処理が含まれる
- 変更により下位互換性が維持される
- 更新には適切なドキュメントが含まれます
- 列操作はデータの整合性を維持します
- 数式参照は適切に処理されます