Smartsheet MCP-Server
Ein Model Context Protocol (MCP)-Server ermöglicht eine nahtlose Integration mit Smartsheet und automatisierte Vorgänge an Smartsheet-Dokumenten über eine standardisierte Schnittstelle. Dieser Server schließt die Lücke zwischen KI-gestützten Automatisierungstools und der leistungsstarken Kollaborationsplattform von Smartsheet.
Überblick
Der Smartsheet MCP Server ermöglicht intelligente Interaktionen mit Smartsheet und bietet robuste Tools für Dokumentenverwaltung, Datenoperationen und Spaltenanpassung. Er ist eine wichtige Komponente in automatisierten Workflows und ermöglicht KI-Systemen die programmgesteuerte Interaktion mit Smartsheet-Daten unter Wahrung der Datenintegrität und Durchsetzung von Geschäftsregeln.
Hauptvorteile
- Intelligente Integration : Nahtlose Verbindung von KI-Systemen mit der Kollaborationsplattform von Smartsheet
- Datenintegrität : Erzwingt Validierungsregeln und gewährleistet die referenzielle Integrität aller Vorgänge
- Formelverwaltung : Behält Formelreferenzen bei und aktualisiert sie automatisch
- Flexible Konfiguration : Unterstützt verschiedene Spaltentypen und komplexe Datenstrukturen
- Fehlerresistenz : Implementiert umfassende Fehlerbehandlung und Validierung auf mehreren Ebenen
- Healthcare Analytics : Spezialisierte Analysefunktionen für klinische und Forschungsdaten
- Stapelverarbeitung : Effiziente Handhabung großer Datensätze im Gesundheitswesen
- Benutzerdefiniertes Scoring : Flexible Bewertungssysteme für Initiativen und Forschung im Gesundheitswesen
Anwendungsfälle
- Analytik für klinische Forschung
- Bewertung der Protokollkonformität
- Patientendatenanalyse
- Forschungsfolgenabschätzung
- Verarbeitung klinischer Studiendaten
- Automatisierte Zusammenfassung von Forschungsnotizen
- Krankenhausbetrieb
- Analyse der Ressourcennutzung
- Bewertung der Patientenzufriedenheit
- Kennzahlen zur Abteilungseffizienz
- Analyse der Mitarbeiterleistung
- Verfolgung von Qualitätsmetriken
- Innovationen im Gesundheitswesen
- Bewertung der Ausrichtung bei Kindern
- Innovationsfolgenabschätzung
- Forschungspriorisierung
- Machbarkeitsanalyse der Umsetzung
- Beurteilung des klinischen Werts
- Automatisiertes Dokumentenmanagement
- Programmatische Änderungen der Blattstruktur
- Dynamische Spaltenerstellung und -verwaltung
- Automatisierte Datenvalidierung und -formatierung
- Datenoperationen
- Massendatenaktualisierungen mit Integritätsprüfungen
- Intelligente Duplikatserkennung
- Formelbewusste Modifikationen
- Systemintegration
- KI-gesteuerte Blattanpassung
- Automatisierte Berichtsworkflows
- Systemübergreifende Datensynchronisation
Integrationspunkte
Der Server ist integriert mit:
- Smartsheet-API für Datenoperationen
- MCP-Protokoll für standardisierte Kommunikation
- Lokale Entwicklungstools über die stdio-Schnittstelle
- Überwachungssysteme durch strukturiertes Logging
Merkmale
Werkzeuge
get_column_map (Lesen)- Ruft Spaltenzuordnung und Beispieldaten aus einem Smartsheet ab
- Bietet detaillierte Spaltenmetadaten, darunter:
- Spaltentypen (Systemspalten, Formeln, Auswahllisten)
- Validierungsregeln
- Formatangaben
- Automatische Nummerierungskonfigurationen
- Gibt Beispieldaten für den Kontext zurück
- Enthält Anwendungsbeispiele zum Schreiben von Daten
smartsheet_write (Erstellen)- Schreibt neue Zeilen in Smartsheet mit intelligenter Handhabung von:
- Systemverwaltete Spalten
- Mehrfachauswahl von Auswahllistenwerten
- Formelbasierte Spalten
- Implementiert die automatische Duplikatserkennung
- Gibt detaillierte Operationsergebnisse einschließlich Zeilen-IDs zurück
smartsheet_update (Aktualisieren)- Aktualisiert vorhandene Zeilen in einem Smartsheet
- Unterstützt teilweise Aktualisierungen (Ändern bestimmter Felder)
- Bewahrt die Datenintegrität durch Validierung
- Behandelt Mehrfachauswahlfelder konsistent
- Gibt Erfolgs-/Fehlerdetails pro Zeile zurück
smartsheet_delete (Löschen)- Löscht Zeilen aus einem Smartsheet
- Unterstützt das Batchlöschen mehrerer Zeilen
- Überprüft die Existenz und Berechtigungen von Zeilen
- Gibt detaillierte Operationsergebnisse zurück
smartsheet_search (Suche)- Führt eine erweiterte Suche über alle Blätter hinweg durch
- Unterstützt mehrere Suchmodi:
- Textsuche mit Regex-Unterstützung
- Genaue Werteübereinstimmung für PICKLIST-Spalten
- Groß-/Kleinschreibung und ganze Wörter
- Spaltenspezifische Suchfunktionen
- Widerrufsfolgen:
- Übereinstimmende Zeilen-IDs (primäres Ergebnis)
- Detaillierte Spielinformationen
- Suchmetadaten und Statistiken
smartsheet_add_column (Spaltenverwaltung)- Fügt einem Smartsheet neue Spalten hinzu
- Unterstützt alle Spaltentypen:
- TEXT_NUMBER
- DATUM
- Kontrollkästchen
- AUSWAHLLISTE
- KONTAKTLISTE
- Konfigurierbare Optionen:
- Positionsindex
- Validierungsregeln
- Formeldefinitionen
- Auswahllistenoptionen
- Erzwingt Spaltenbegrenzung (400) mit Validierung
- Gibt detaillierte Spalteninformationen zurück
smartsheet_delete_column (Spaltenverwaltung)- Sicheres Löschen von Spalten mit Abhängigkeitsprüfung
- Validiert Formelreferenzen vor dem Löschen
- Verhindert das Löschen von Spalten, die in Formeln verwendet werden
- Gibt detaillierte Abhängigkeitsinformationen zurück
- Unterstützt die Option zum erzwungenen Löschen
smartsheet_rename_column (Spaltenverwaltung)- Benennt Spalten um und behält dabei die Beziehungen bei
- Aktualisiert Formelreferenzen automatisch
- Bewahrt die Datenintegrität
- Überprüft die Eindeutigkeit des Namens
- Gibt detaillierte Update-Informationen zurück
smartsheet_bulk_update (Bedingte Updates)- Führt bedingte Massenaktualisierungen basierend auf Regeln durch
- Unterstützt die Auswertung komplexer Zustände:
- Mehrere Operatoren (gleich, enthält, größer als usw.)
- Typspezifische Vergleiche (Text, Datum, Zahlen)
- Leere/Nicht-leere Schecks
- Stapelverarbeitung mit konfigurierbarer Größe
- Umfassende Fehlerbehandlung und Rollback
- Detaillierte Verfolgung der Betriebsergebnisse
start_batch_analysis (Analyse im Gesundheitswesen)
- Verarbeitet ganze Blätter oder ausgewählte Zeilen mit KI-Analyse
- Unterstützt mehrere Analysetypen:
- Zusammenfassung der klinischen Notizen
- Sentimentanalyse des Patientenfeedbacks
- Benutzerdefiniertes Scoring für Gesundheitsinitiativen
- Forschungsfolgenabschätzung
- Merkmale:
- Automatische Stapelverarbeitung (50 Zeilen pro Stapel)
- Fortschrittsverfolgung und Statusüberwachung
- Fehlerbehandlung mit detaillierter Berichterstattung
- Anpassbare Analyseziele
- Unterstützung für mehrere Quellspalten
get_job_status (Analyseüberwachung)
- Verfolgt den Fortschritt der Batchanalyse
- Bietet detaillierte Jobstatistiken:
- Gesamtzahl der zu verarbeitenden Zeilen
- Anzahl der verarbeiteten Zeilen
- Zeilenzählung fehlgeschlagen
- Verarbeitungszeitstempel
- Statusaktualisierungen in Echtzeit
- Umfassende Fehlerberichterstattung
cancel_batch_analysis (Job-Steuerung)
- Bricht laufende Batchanalysejobs ab
- Ordentlicher Prozessabbruch
- Behält die Datenkonsistenz bei
- Gibt den endgültigen Auftragsstatus zurück
list_workspaces (Arbeitsbereichsverwaltung)
- Listet alle zugänglichen Arbeitsbereiche auf
- Gibt Arbeitsbereichs-IDs, Namen und Permalinks zurück
- Enthält Informationen zur Zugriffsebene
- Unterstützt die unternehmensweite Arbeitsbereichserkennung
get_workspace (Arbeitsbereichsverwaltung)
- Ruft detaillierte Arbeitsbereichsinformationen ab
- Die Rückgaben enthielten Blätter, Ordner, Berichte und Dashboards
- Bietet Zugriffsebenen- und Berechtigungsdetails
- Unterstützt die Erkundung von Arbeitsbereichsinhalten
create_workspace (Arbeitsbereichsverwaltung)
- Erstellt einen neuen Arbeitsbereich mit dem angegebenen Namen
- Gibt die neue Arbeitsbereichs-ID und Bestätigung zurück
- Ermöglicht die programmgesteuerte Organisation des Arbeitsbereichs
- Unterstützt die Migration von veralteten Ordnerendpunkten
create_sheet_in_workspace (Arbeitsbereichsverwaltung)
- Erstellt ein neues Blatt direkt in einem Arbeitsbereich
- Unterstützt alle Spaltentypen und -konfigurationen
- Gibt die neue Blatt-ID und Details zurück
- Ermöglicht die programmgesteuerte Erstellung und Organisation von Arbeitsblättern
list_workspace_sheets (Arbeitsbereichsverwaltung)
- Listet alle Blätter in einem bestimmten Arbeitsbereich auf
- Gibt Blatt-IDs, Namen und Permalinks zurück
- Enthält Erstellungs- und Änderungszeitstempel
- Unterstützt die Erkennung von Arbeitsbereichsinhalten
Schlüsselfunktionen
- Spaltentypverwaltung
- Verarbeitet Systemspaltentypen (AUTO_NUMBER, CREATED_DATE usw.)
- Unterstützt Formelanalyse und Abhängigkeitsverfolgung
- Verwaltet Auswahllistenoptionen und Mehrfachauswahlwerte
- Umfangreiche Spaltenoperationen (Hinzufügen, Löschen, Umbenennen)
- Beibehaltung und Aktualisierung von Formelreferenzen
- Datenvalidierung
- Automatische Duplikatserkennung
- Validierung des Spaltentyps
- Überprüfung des Datenformats
- Spaltenabhängigkeitsanalyse
- Validierung der Eindeutigkeit des Namens
- Suchfunktion
- Erweiterte Suchfunktionen
- Typbewusste Suche:
- Genaue Übereinstimmung für PICKLIST-Werte
- Mustervergleich für Textfelder
- Numerische Vergleiche
- Konfigurierbare Suchoptionen:
- Groß- und Kleinschreibung
- Ganzes Wort finden
- Spaltenfilterung
- Umfassende Ergebnisse:
- Zeilen-IDs für übereinstimmende Zeilen
- Detaillierter Spielkontext
- Suchstatistiken
- Metadatenverarbeitung
- Extrahiert und verarbeitet Spaltenmetadaten
- Behandelt Validierungsregeln
- Verwaltet Formatspezifikationen
- Verfolgt Formelabhängigkeiten
- Behält Spaltenbeziehungen bei
- Analytik im Gesundheitswesen
- Zusammenfassung der klinischen Notizen
- Stimmungsanalyse des Patientenfeedbacks
- Bewertung der Protokollkonformität
- Forschungsfolgenabschätzung
- Analyse der Ressourcennutzung
- Stapelverarbeitung
- Automatische Zeilenstapelverarbeitung (50 Zeilen pro Stapel)
- Fortschrittsverfolgung und -überwachung
- Fehlerbehandlung und Wiederherstellung
- Anpassbare Verarbeitungsziele
- Unterstützung mehrspaltiger Analysen
- Auftragsverwaltung
- Echtzeit-Statusüberwachung
- Detaillierte Fortschrittsverfolgung
- Fehlerberichterstattung und -protokollierung
- Unterstützung bei der Auftragsstornierung
- Steuerung von Batchvorgängen
Aufstellen
Voraussetzungen
- Node.js und npm
- Conda (für Umgebungsmanagement)
- Smartsheet-API-Zugriffstoken
Umgebungs-Setup
- Erstellen Sie eine dedizierte Conda-Umgebung:
conda create -n cline_mcp_env python=3.12 nodejs -y
conda activate cline_mcp_env
- Installieren Sie Node.js-Abhängigkeiten:
- Installieren Sie das Python-Paket:
cd smartsheet_ops
pip install -e .
cd ..
- Erstellen Sie den TypeScript-Server:
Konfiguration
Der Server erfordert eine entsprechende Konfiguration in Ihren MCP-Einstellungen. Sie können ihn sowohl mit Claude Desktop als auch mit Cline verwenden.
1. Holen Sie sich Ihren Smartsheet-API-Schlüssel
- Bei Smartsheet anmelden
- Gehen Sie zu Konto → Persönliche Einstellungen → API-Zugriff
- Generieren Sie ein neues Zugriffstoken
2. Für Cline konfigurieren
Der Konfigurationspfad hängt von Ihrem Betriebssystem ab:
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
{
"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",
"list_workspaces",
"get_workspace",
"create_workspace",
"create_sheet_in_workspace",
"list_workspace_sheets"
]
}
}
}
Starten des Servers
Der Server startet automatisch, wenn Cline oder Claude Desktop ihn benötigt. Sie können ihn jedoch auch zum Testen manuell starten.
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
Windows :
:: 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
Überprüfen der Installation
- Der Server sollte beim Start „Smartsheet MCP-Server läuft auf stdio“ ausgeben.
- Testen Sie die Verbindung mit einem beliebigen MCP-Tool (z. B. get_column_map).
- Überprüfen Sie, ob das Smartsheet-Paket in der Python-Umgebung installiert ist:
conda activate cline_mcp_env
pip show smartsheet-python-sdk
Anwendungsbeispiele
// 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",
},
});
Daten schreiben (Erstellen)
// 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",
},
],
},
});
Daten suchen
// Basic text search
const result = await use_mcp_tool({
server_name: "smartsheet",
tool_name: "smartsheet_search",
arguments: {
sheet_id: "your-sheet-id",
pattern: "search text",
options: {
case_sensitive: false,
whole_word: false,
columns: ["Column1", "Column2"], // Optional: limit search to specific columns
},
},
});
// Search PICKLIST column with exact matching
const result = await use_mcp_tool({
server_name: "smartsheet",
tool_name: "smartsheet_search",
arguments: {
sheet_id: "your-sheet-id",
pattern: "In Progress",
options: {
columns: ["Status"], // PICKLIST column
case_sensitive: true,
whole_word: true,
},
},
});
Daten aktualisieren (Update)
// 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",
},
},
],
},
});
Daten löschen (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"],
},
});
Beispiele für Gesundheitsanalysen
// 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",
},
});
Beispiele für die Arbeitsbereichsverwaltung
// List all accessible workspaces
const workspaces = await use_mcp_tool({
server_name: "smartsheet",
tool_name: "list_workspaces",
arguments: {},
});
// Get details of a specific workspace
const workspace = await use_mcp_tool({
server_name: "smartsheet",
tool_name: "get_workspace",
arguments: {
workspace_id: "6621332407379844",
},
});
// Create a new workspace
const newWorkspace = await use_mcp_tool({
server_name: "smartsheet",
tool_name: "create_workspace",
arguments: {
name: "Project Management",
},
});
// Create a sheet in a workspace
const newSheet = await use_mcp_tool({
server_name: "smartsheet",
tool_name: "create_sheet_in_workspace",
arguments: {
workspace_id: "6621332407379844",
name: "Task Tracker",
columns: [
{ title: "Task Name", type: "TEXT_NUMBER" },
{ title: "Due Date", type: "DATE" },
{
title: "Status",
type: "PICKLIST",
options: ["Not Started", "In Progress", "Completed"],
},
],
},
});
// List all sheets in a workspace
const sheets = await use_mcp_tool({
server_name: "smartsheet",
tool_name: "list_workspace_sheets",
arguments: {
workspace_id: "6621332407379844",
},
});
Entwicklung
Für die Entwicklung mit automatischem Rebuild:
Debuggen
Da MCP-Server über stdio kommunizieren, kann die Fehlersuche eine Herausforderung darstellen. Der Server implementiert eine umfassende Fehlerprotokollierung und stellt detaillierte Fehlermeldungen über das MCP-Protokoll bereit.
Wichtige Debugging-Funktionen:
- Fehlerprotokollierung in stderr
- Detaillierte Fehlermeldungen in MCP-Antworten
- Typvalidierung auf mehreren Ebenen
- Umfassende Berichterstattung über Betriebsergebnisse
- Abhängigkeitsanalyse für Spaltenoperationen
- Formelreferenzverfolgung
Fehlerbehandlung
Der Server implementiert einen mehrschichtigen Ansatz zur Fehlerbehandlung:
- MCP-Schicht
- Validiert Werkzeugparameter
- Behandelt Fehler auf Protokollebene
- Bietet formatierte Fehlerantworten
- Verwaltet Timeouts und Wiederholungsversuche
- CLI-Schicht
- Validiert Befehlsargumente
- Behandelt Ausführungsfehler
- Formatiert Fehlermeldungen als JSON
- Validiert Spaltenoperationen
- Operationsebene
- Behandelt Smartsheet-API-Fehler
- Validiert Datentypen und -formate
- Bietet einen detaillierten Fehlerkontext
- Verwaltet Spaltenabhängigkeiten
- Validiert Formelreferenzen
- Gewährleistet die Datenintegrität
Beitragen
Beiträge sind willkommen! Bitte stellen Sie sicher:
- TypeScript/Python-Code folgt dem vorhandenen Stil
- Zu den neuen Funktionen gehört eine entsprechende Fehlerbehandlung
- Änderungen gewährleisten die Abwärtskompatibilität
- Updates beinhalten entsprechende Dokumentation
- Spaltenoperationen wahren die Datenintegrität
- Formelreferenzen werden ordnungsgemäß behandelt