Smartsheet
STDIOMCP server for Smartsheet integration with AI automation for data management and healthcare analytics.
MCP server for Smartsheet integration with AI automation for data management and healthcare analytics.
A Model Context Protocol (MCP) server that provides seamless integration with Smartsheet, enabling automated operations on Smartsheet documents through a standardized interface. This server bridges the gap between AI-powered automation tools and Smartsheet's powerful collaboration platform.
The Smartsheet MCP Server is designed to facilitate intelligent interactions with Smartsheet, providing a robust set of tools for document management, data operations, and column customization. It serves as a critical component in automated workflows, enabling AI systems to programmatically interact with Smartsheet data while maintaining data integrity and enforcing business rules.
Clinical Research Analytics
Hospital Operations
Healthcare Innovation
Automated Document Management
Data Operations
System Integration
The server integrates with:
get_column_map (Read)
get_sheet_info (Read - Alias)
get_column_map providing identical functionalitysmartsheet_write (Create)
smartsheet_update (Update)
smartsheet_delete (Delete)
smartsheet_search (Search)
smartsheet_add_column (Column Management)
smartsheet_delete_column (Column Management)
smartsheet_rename_column (Column Management)
smartsheet_bulk_update (Conditional Updates)
get_all_row_ids (Utility)
start_batch_analysis (Healthcare Analytics)
get_job_status (Analysis Monitoring)
cancel_batch_analysis (Job Control)
list_workspaces (Workspace Management)
get_workspace (Workspace Management)
create_workspace (Workspace Management)
create_sheet_in_workspace (Workspace Management)
list_workspace_sheets (Workspace Management)
smartsheet_upload_attachment (Attachment Management)
smartsheet_get_attachments (Attachment Management)
smartsheet_download_attachment (Attachment Management)
smartsheet_delete_attachment (Attachment Management)
smartsheet_create_discussion (Discussion Management)
smartsheet_add_comment (Discussion Management)
smartsheet_get_discussions (Discussion Management)
smartsheet_get_comments (Discussion Management)
smartsheet_delete_comment (Discussion Management)
smartsheet_get_cell_history (Cell History & Audit)
smartsheet_get_row_history (Cell History & Audit)
smartsheet_get_sheet_cross_references (Cross-Sheet References)
smartsheet_find_sheet_references (Cross-Sheet References)
smartsheet_validate_cross_references (Cross-Sheet References)
smartsheet_create_cross_reference (Cross-Sheet References)
The server provides both static resources and dynamic resource templates for enhanced data access and contextual information.
smartsheet://templates/project-plan - Project Plan Template
smartsheet://templates/task-tracker - Task Tracker Template
smartsheet://schemas/column-types - Column Types Reference
smartsheet://best-practices/formulas - Formula Best Practices
smartsheet://{sheet_id}/summary - Sheet Summary
smartsheet://{sheet_id}/gantt-data - Gantt Chart Data
smartsheet://{workspace_id}/overview - Workspace Overview
smartsheet://{sheet_id}/dependencies - Dependency Map
smartsheet://{sheet_id}/health-report - Sheet Health Report
Intelligent prompt templates that provide guided assistance for common Smartsheet operations and analysis.
create_project_plan - Project Plan Creation Guide
analyze_project_status - Project Health Analysis
optimize_workflow - Workflow Optimization
generate_insights - Data Insights Extraction
create_dashboard_summary - Executive Dashboard Creation
setup_conditional_formatting - Conditional Formatting Guide
Column Type Management
Data Validation
Search Functionality
Metadata Handling
Healthcare Analytics
Batch Processing
Job Management
Cross-Sheet References
conda create -n cline_mcp_env python=3.12 nodejs -y conda activate cline_mcp_env
npm install
cd smartsheet_ops pip install -e . cd ..
Note: The Python package includes dependencies for:
smartsheet-python-sdk - Smartsheet API clientpython-dotenv - Environment variable managementopenai - Azure OpenAI integrationtiktoken - Token counting for AI analysisnpm run build
The server supports two transport modes:
The configuration path depends on your operating system:
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", "--transport", "stdio" ], "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", "get_all_row_ids", "list_workspaces", "get_workspace", "create_workspace", "create_sheet_in_workspace", "list_workspace_sheets" ] } } }
For web-based MCP clients or network access, use the HTTP transport mode:
Start the server:
# Start with default port (3000) SMARTSHEET_API_KEY=your-api-key PYTHON_PATH=/path/to/python smartsheet-server --transport http # Start with custom port SMARTSHEET_API_KEY=your-api-key PYTHON_PATH=/path/to/python smartsheet-server --transport http --port 8080
Client Configuration:
{ "mcpServers": { "smartsheet-server": { "type": "http", "url": "http://localhost:3000/mcp", "headers": { "Authorization": "Bearer your-optional-auth-token" } } } }
Health Check:
The HTTP server provides a health check endpoint:
curl http://localhost:3000/health # Response: {"status":"ok","server":"smartsheet-mcp"}
The server will start automatically when Cline or Claude Desktop needs it. However, you can also start it manually for testing.
macOS/Linux:
# Activate the environment conda activate cline_mcp_env # Start with STDIO transport (default) PYTHON_PATH=/Users/[username]/anaconda3/envs/cline_mcp_env/bin/python3 SMARTSHEET_API_KEY=your-api-key node build/index.js # Or explicitly specify STDIO transport PYTHON_PATH=/Users/[username]/anaconda3/envs/cline_mcp_env/bin/python3 SMARTSHEET_API_KEY=your-api-key node build/index.js --transport stdio
Windows:
:: Activate the environment conda activate cline_mcp_env :: Start with STDIO transport set PYTHON_PATH=C:\Users\[username]\anaconda3\envs\cline_mcp_env\python.exe set SMARTSHEET_API_KEY=your-api-key node build\index.js --transport stdio
For web-based clients or network access:
macOS/Linux:
# Activate the environment conda activate cline_mcp_env # Start HTTP server on default port (3000) PYTHON_PATH=/Users/[username]/anaconda3/envs/cline_mcp_env/bin/python3 SMARTSHEET_API_KEY=your-api-key node build/index.js --transport http # Start HTTP server on custom port PYTHON_PATH=/Users/[username]/anaconda3/envs/cline_mcp_env/bin/python3 SMARTSHEET_API_KEY=your-api-key node build/index.js --transport http --port 8080
Windows:
:: Activate the environment conda activate cline_mcp_env :: Start HTTP 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 --transport http --port 3000
# View help node build/index.js --help # Available options: --transport <type> # "stdio" (default) or "http" --port <number> # HTTP port (default: 3000, only used with --transport http) --help, -h # Show help message
curl http://localhost:3000/health{"status":"ok","server":"smartsheet-mcp"}Check the Python environment has the required packages installed:
conda activate cline_mcp_env pip show smartsheet-python-sdk openai tiktoken python-dotenv
The Python package should include these key dependencies:
smartsheet-python-sdk>=2.105.1 - Smartsheet API clientopenai>=1.0.0 - Azure OpenAI integrationtiktoken>=0.5.0 - Token counting for AI analysispython-dotenv>=1.0.0 - Environment variable management// 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", }, ], }, });
// 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, }, }, });
// 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", rowIds: ["row1", "row2", "row3"], // Optional: specify rows, or omit for all rows 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", rowIds: ["row1", "row2"], // Optional: specify rows, or omit for all rows }, }); // 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", rowIds: ["row1", "row2"], // Optional: specify rows, or omit for all rows }, }); // Example 4: Get All Row IDs for Batch Processing const allRows = await use_mcp_tool({ server_name: "smartsheet", tool_name: "get_all_row_ids", arguments: { sheet_id: "your-sheet-id", }, }); // Example 5: Monitor Analysis Job Progress const jobStatus = await use_mcp_tool({ server_name: "smartsheet", tool_name: "get_job_status", arguments: { sheet_id: "your-sheet-id", jobId: "job-uuid-from-start-analysis", }, });
// 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", }, });
// Access static resources const projectTemplate = await access_mcp_resource({ server_name: "smartsheet", uri: "smartsheet://templates/project-plan", }); const columnTypes = await access_mcp_resource({ server_name: "smartsheet", uri: "smartsheet://schemas/column-types", }); const formulaGuide = await access_mcp_resource({ server_name: "smartsheet", uri: "smartsheet://best-practices/formulas", }); // Access dynamic resources const sheetSummary = await access_mcp_resource({ server_name: "smartsheet", uri: "smartsheet://8596778555232132/summary", }); const ganttData = await access_mcp_resource({ server_name: "smartsheet", uri: "smartsheet://8596778555232132/gantt-data", }); const workspaceOverview = await access_mcp_resource({ server_name: "smartsheet", uri: "smartsheet://6621332407379844/overview", }); const dependencyMap = await access_mcp_resource({ server_name: "smartsheet", uri: "smartsheet://8596778555232132/dependencies", }); const healthReport = await access_mcp_resource({ server_name: "smartsheet", uri: "smartsheet://8596778555232132/health-report", });
// Project plan creation guidance const projectPlanPrompt = await use_mcp_tool({ server_name: "smartsheet", tool_name: "get_prompt", arguments: { name: "create_project_plan", arguments: { project_name: "Website Redesign", project_type: "software", duration_estimate: "3 months", }, }, }); // Project health analysis const analysisPrompt = await use_mcp_tool({ server_name: "smartsheet", tool_name: "get_prompt", arguments: { name: "analyze_project_status", arguments: { sheet_id: "8596778555232132", focus_area: "timeline", }, }, }); // Workflow optimization suggestions const optimizationPrompt = await use_mcp_tool({ server_name: "smartsheet", tool_name: "get_prompt", arguments: { name: "optimize_workflow", arguments: { sheet_id: "8596778555232132", workflow_type: "approval", }, }, }); // Data insights extraction const insightsPrompt = await use_mcp_tool({ server_name: "smartsheet", tool_name: "get_prompt", arguments: { name: "generate_insights", arguments: { sheet_id: "8596778555232132", insight_type: "bottlenecks", }, }, }); // Executive dashboard creation const dashboardPrompt = await use_mcp_tool({ server_name: "smartsheet", tool_name: "get_prompt", arguments: { name: "create_dashboard_summary", arguments: { workspace_id: "6621332407379844", summary_focus: "risks", }, }, }); // Conditional formatting setup const formattingPrompt = await use_mcp_tool({ server_name: "smartsheet", tool_name: "get_prompt", arguments: { name: "setup_conditional_formatting", arguments: { sheet_id: "8596778555232132", formatting_goal: "status indicators", }, }, });
For development with auto-rebuild:
npm run watch
This project implements a comprehensive 8-stage CI/CD pipeline with GitHub Actions, ensuring code quality, security, and reliability across all components.
The CI/CD pipeline consists of 8 coordinated jobs that run in parallel and sequence for optimal efficiency:
Quality Assurance:
Performance Optimization:
Integration and Deployment:
# Comprehensive testing on main branches - push: [main, develop] - pull_request: [main, develop] # Additional workflows - release: version tags (v*.*.*) - security: weekly dependency scans - performance: PR-specific testing
The pipeline provides comprehensive notifications and artifact management, ensuring all stakeholders have visibility into build status, test results, and deployment readiness.
This project maintains comprehensive test coverage and quality assurance across both TypeScript and Python components with automated CI/CD pipelines.
Test Status: 54/54 TypeScript tests passing, 5/5 Python tests passing
Our comprehensive testing strategy includes:
Current coverage metrics:
# Essential testing commands for daily development npm run ci:check # Pre-commit validation (recommended before push) npm run test:all # Run all tests with coverage npm run coverage # Full coverage analysis with combined reporting npm run coverage:open # View coverage reports in browser # Individual test suites npm test # TypeScript tests only npm run test:python # Python tests only npm run test:coverage # TypeScript with coverage npm run test:python:coverage # Python with coverage # Development testing npm run test:watch # Watch mode for continuous testing npm run coverage:clean # Coverage without external uploads
# Quality assurance npm run lint # ESLint for TypeScript npm run lint:fix # Auto-fix linting issues npm run format # Prettier code formatting npm run typecheck # TypeScript type validation # Coverage and reporting npm run badges:update # Generate coverage badges npm run coverage:ci # CI-optimized coverage reporting npm run coverage:view # Open all coverage reports npm run coverage:combined # View combined coverage report # Build and validation npm run build # Build TypeScript npm run watch # Development build with watch npm run inspector # MCP inspector for tool testing
After running tests, detailed reports are available:
./coverage/index.html./smartsheet_ops/coverage/index.html./coverage-combined/index.htmlThe project enforces strict quality standards:
Build and run the containerized version:
# Build Docker image docker build -t smartsheet-server . # Run with environment variables docker run -e SMARTSHEET_API_KEY=your_key -e PYTHON_PATH=/usr/local/bin/python smartsheet-server
Since MCP servers communicate over stdio, debugging can be challenging. The server implements comprehensive error logging and provides detailed error messages through the MCP protocol.
Key debugging features:
The server implements a multi-layer error handling approach:
MCP Layer
CLI Layer
Operations Layer
Contributions are welcome! Please ensure: