The Smartsheet MCP Server bridges automated operations on Smartsheet documents through the Model Context Protocol (MCP), enabling intelligent integration with AI systems.
Column Management: Add, delete, and rename columns with validation, formula parsing, and dependency checking.
Data Operations: Read, write, update, delete, and search data with support for bulk operations, conditional updates, and duplicate detection.
Healthcare Analytics: Perform batch analysis for clinical note summarization, sentiment analysis, and custom scoring for healthcare initiatives and hospital operations.
Batch Processing: Efficiently handle large datasets with automatic batching, progress tracking, and job management.
System Integration: Connect Smartsheet API with MCP protocol for AI-driven workflows and cross-system data synchronization.
Validation & Integrity: Enforce data validation, dependency checks, and comprehensive error handling to maintain data integrity.
Integrates with Azure OpenAI API for batch analysis capabilities, enabling summarization, sentiment analysis, custom scoring, and research impact assessment on Smartsheet data.
Provides integration with Smartsheet platform, enabling intelligent operations for document management, data manipulation, column customization, batch analysis, and conditional updates of Smartsheet documents. Supports healthcare-specific analytics including clinical research, hospital operations, and healthcare innovation.
Smartsheet MCP Server
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.
Overview
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.
Key Benefits
- Intelligent Integration: Seamlessly connects AI systems with Smartsheet's collaboration platform
- Data Integrity: Enforces validation rules and maintains referential integrity across operations
- Formula Management: Preserves and updates formula references automatically
- Flexible Configuration: Supports various column types and complex data structures
- Error Resilience: Implements comprehensive error handling and validation at multiple layers
- Healthcare Analytics: Specialized analysis capabilities for clinical and research data
- Batch Processing: Efficient handling of large healthcare datasets
- Custom Scoring: Flexible scoring systems for healthcare initiatives and research
Use Cases
- Clinical Research Analytics
- Protocol compliance scoring
- Patient data analysis
- Research impact assessment
- Clinical trial data processing
- Automated research note summarization
- Hospital Operations
- Resource utilization analysis
- Patient satisfaction scoring
- Department efficiency metrics
- Staff performance analytics
- Quality metrics tracking
- Healthcare Innovation
- Pediatric alignment scoring
- Innovation impact assessment
- Research prioritization
- Implementation feasibility analysis
- Clinical value assessment
- Automated Document Management
- Programmatic sheet structure modifications
- Dynamic column creation and management
- Automated data validation and formatting
- Data Operations
- Bulk data updates with integrity checks
- Intelligent duplicate detection
- Formula-aware modifications
- System Integration
- AI-driven sheet customization
- Automated reporting workflows
- Cross-system data synchronization
Integration Points
The server integrates with:
- Smartsheet API for data operations
- MCP protocol for standardized communication
- Local development tools via stdio interface
- Monitoring systems through structured logging
Features
Tools (34 Available)
get_column_map
(Read)- Retrieves column mapping and sample data from a Smartsheet
- Provides detailed column metadata including:
- Column types (system columns, formulas, picklists)
- Validation rules
- Format specifications
- Auto-number configurations
- Returns sample data for context
- Includes usage examples for writing data
get_sheet_info
(Read - Alias)- Alias for
get_column_map
providing identical functionality - Maintains backward compatibility with existing integrations
- Alias for
smartsheet_write
(Create)- Writes new rows to Smartsheet with intelligent handling of:
- System-managed columns
- Multi-select picklist values
- Formula-based columns
- Implements automatic duplicate detection
- Appends new rows to the bottom of the sheet (after existing entries)
- Returns detailed operation results including row IDs
- Writes new rows to Smartsheet with intelligent handling of:
smartsheet_update
(Update)- Updates existing rows in a Smartsheet
- Supports partial updates (modify specific fields)
- Maintains data integrity with validation
- Handles multi-select fields consistently
- Returns success/failure details per row
smartsheet_delete
(Delete)- Deletes rows from a Smartsheet
- Supports batch deletion of multiple rows
- Validates row existence and permissions
- Returns detailed operation results
smartsheet_search
(Search)- Performs advanced search across sheets
- Supports multiple search modes:
- Text search with regex support
- Exact value matching for PICKLIST columns
- Case-sensitive and whole word options
- Column-specific search capabilities
- Returns:
- Matched row IDs (primary result)
- Detailed match information
- Search metadata and statistics
smartsheet_add_column
(Column Management)- Adds new columns to a Smartsheet
- Supports all column types:
- TEXT_NUMBER
- DATE
- CHECKBOX
- PICKLIST
- CONTACT_LIST
- Configurable options:
- Position index
- Validation rules
- Formula definitions
- Picklist options
- Enforces column limit (400) with validation
- Returns detailed column information
smartsheet_delete_column
(Column Management)- Safely deletes columns with dependency checking
- Validates formula references before deletion
- Prevents deletion of columns used in formulas
- Returns detailed dependency information
- Supports force deletion option
smartsheet_rename_column
(Column Management)- Renames columns while preserving relationships
- Updates formula references automatically
- Maintains data integrity
- Validates name uniqueness
- Returns detailed update information
smartsheet_bulk_update
(Conditional Updates)- Performs conditional bulk updates based on rules
- Supports complex condition evaluation:
- Multiple operators (equals, contains, greaterThan, etc.)
- Type-specific comparisons (text, dates, numbers)
- Empty/non-empty checks
- Batch processing with configurable size
- Comprehensive error handling and rollback
- Detailed operation results tracking
get_all_row_ids
(Utility)- Retrieves all row IDs from a Smartsheet
- Useful for batch operations and data analysis
- Returns complete list of row identifiers
- Supports large sheets efficiently
start_batch_analysis
(Healthcare Analytics)- Processes entire sheets or selected rows with AI analysis
- Supports multiple analysis types:
- Summarization of clinical notes
- Sentiment analysis of patient feedback
- Custom scoring for healthcare initiatives
- Research impact assessment
- Features:
- Automatic batch processing (3 rows per batch for optimal performance)
- Progress tracking and status monitoring
- Error handling with detailed reporting
- Customizable analysis goals via Azure OpenAI
- Support for multiple source columns
- Token-aware content chunking for large text
get_job_status
(Analysis Monitoring)- Tracks batch analysis progress
- Provides detailed job statistics:
- Total rows to process
- Processed row count
- Failed row count
- Processing timestamps
- Real-time status updates
- Comprehensive error reporting
cancel_batch_analysis
(Job Control)- Cancels running batch analysis jobs
- Graceful process termination
- Maintains data consistency
- Returns final job status
list_workspaces
(Workspace Management)- Lists all accessible workspaces
- Returns workspace IDs, names, and permalinks
- Includes access level information
- Supports organization-wide workspace discovery
get_workspace
(Workspace Management)- Retrieves detailed workspace information
- Returns contained sheets, folders, reports, and dashboards
- Provides access level and permission details
- Supports workspace content exploration
create_workspace
(Workspace Management)- Creates a new workspace with specified name
- Returns the new workspace ID and confirmation
- Enables programmatic workspace organization
- Supports migration from deprecated folder endpoints
create_sheet_in_workspace
(Workspace Management)- Creates a new sheet directly in a workspace
- Supports all column types and configurations
- Returns the new sheet ID and details
- Enables programmatic sheet creation and organization
list_workspace_sheets
(Workspace Management)- Lists all sheets in a specific workspace
- Returns sheet IDs, names, and permalinks
- Includes creation and modification timestamps
- Supports workspace content discovery
smartsheet_upload_attachment
(Attachment Management)- Upload files to sheets, rows, or comments
- Supports multiple attachment types and file size validation
- Returns attachment metadata and upload status
smartsheet_get_attachments
(Attachment Management)- List all attachments for sheet or row
- Returns comprehensive attachment metadata
- Includes file URLs, sizes, and creator information
smartsheet_download_attachment
(Attachment Management)- Download specific attachments to local filesystem
- Creates directories as needed and verifies downloads
- Returns download status and file information
smartsheet_delete_attachment
(Attachment Management)- Remove attachments from sheets
- Validates permissions and returns deletion status
smartsheet_create_discussion
(Discussion Management)- Create new discussion threads on sheets or rows
- Supports initial comments and optional titles
- Returns discussion metadata and creation status
smartsheet_add_comment
(Discussion Management)- Add comments to existing discussions
- Maintains threaded conversation structure
- Returns comment details and timestamps
smartsheet_get_discussions
(Discussion Management)- List all discussions for sheets or rows
- Optional inclusion of all comments in response
- Returns discussion metadata and participant information
smartsheet_get_comments
(Discussion Management)- Get all comments in a specific discussion thread
- Includes attachment information if present
- Returns chronological comment history
smartsheet_delete_comment
(Discussion Management)- Delete specific comments from discussions
- Validates permissions before deletion
- Returns deletion confirmation
smartsheet_get_cell_history
(Cell History & Audit)- Get modification history for individual cells
- Includes user attribution and timestamps
- Tracks value changes, formulas, and formatting
smartsheet_get_row_history
(Cell History & Audit)- Get change history for entire rows
- Provides chronological timeline of all cell changes
- Supports specific column filtering and complete audit trails
smartsheet_get_sheet_cross_references
(Cross-Sheet References)- Analyze all cross-sheet references within a sheet
- Identify formulas that reference other sheets
- Detailed analysis of formula patterns and dependencies
smartsheet_find_sheet_references
(Cross-Sheet References)- Find all sheets that reference a specific target sheet
- Search across workspace or entire accessible sheets
- Comprehensive reference mapping and impact analysis
smartsheet_validate_cross_references
(Cross-Sheet References)- Validate all cross-sheet references for broken links
- Identify inaccessible or deleted referenced sheets
- Suggest alternative sheets for broken references
smartsheet_create_cross_reference
(Cross-Sheet References)- Create INDEX_MATCH, VLOOKUP, SUMIF, COUNTIF formulas
- Build cross-sheet reference formulas programmatically
- Support for custom formula templates and multiple formula types
Resources (4 Static + 5 Dynamic Templates)
The server provides both static resources and dynamic resource templates for enhanced data access and contextual information.
Static Resources
smartsheet://templates/project-plan
- Project Plan Template- Pre-built project plan template with best practices
- Includes optimal column structure for task management
- Provides guidance on dependencies and resource allocation
smartsheet://templates/task-tracker
- Task Tracker Template- Simple task tracking template for team collaboration
- Focused on progress monitoring without complex dependencies
- Ideal for agile teams and simple workflows
smartsheet://schemas/column-types
- Column Types Reference- Complete reference of all supported Smartsheet column types
- Includes API support level for each type (full, limited, read-only)
- Essential for understanding column capabilities and limitations
smartsheet://best-practices/formulas
- Formula Best Practices- Common formula patterns and calculation examples
- Best practices for performance and maintainability
- Cross-sheet reference guidance
Dynamic Resource Templates
smartsheet://{sheet_id}/summary
- Sheet Summary- Auto-generated summary with key metrics and health status
- Progress indicators and completion statistics
- Real-time analysis of sheet data
smartsheet://{sheet_id}/gantt-data
- Gantt Chart Data- Standardized Gantt chart data format for visualization
- Timeline data optimized for project management tools
- Dependency relationships and critical path information
smartsheet://{workspace_id}/overview
- Workspace Overview- Comprehensive overview of workspace contents
- All sheets, reports, and dashboards in structured format
- Access levels and organizational hierarchy
smartsheet://{sheet_id}/dependencies
- Dependency Map- Visual dependency mapping for project sheets
- Task relationships and critical path analysis
- Bottleneck identification and optimization suggestions
smartsheet://{sheet_id}/health-report
- Sheet Health Report- Health analysis identifying data quality issues
- Missing data detection and broken formula identification
- Optimization opportunities and recommendations
Prompts (6 Available)
Intelligent prompt templates that provide guided assistance for common Smartsheet operations and analysis.
create_project_plan
- Project Plan Creation Guide- Guided project plan creation with best practices
- Template suggestions based on project type and duration
- Work breakdown structure recommendations
analyze_project_status
- Project Health Analysis- Comprehensive project health analysis with recommendations
- Timeline adherence and resource utilization insights
- Risk identification and mitigation strategies
optimize_workflow
- Workflow Optimization- Suggestions for improving sheet structure and workflows
- Automation opportunities and efficiency improvements
- User experience enhancement recommendations
generate_insights
- Data Insights Extraction- Extract key insights and patterns from sheet data
- Trend analysis and anomaly detection
- Actionable intelligence and decision support
create_dashboard_summary
- Executive Dashboard Creation- Generate executive summaries from multiple sheets
- High-level KPI tracking and strategic insights
- Leadership-focused reporting and recommendations
setup_conditional_formatting
- Conditional Formatting Guide- Step-by-step conditional formatting setup
- Visual data representation best practices
- Status indicators and progress tracking configuration
Key Capabilities
- Column Type Management
- Handles system column types (AUTO_NUMBER, CREATED_DATE, etc.)
- Supports formula parsing and dependency tracking
- Manages picklist options and multi-select values
- Comprehensive column operations (add, delete, rename)
- Formula reference preservation and updates
- Data Validation
- Automatic duplicate detection
- Column type validation
- Data format verification
- Column dependency analysis
- Name uniqueness validation
- Search Functionality
- Advanced search capabilities
- Type-aware searching:
- Exact matching for PICKLIST values
- Pattern matching for text fields
- Numeric comparisons
- Configurable search options:
- Case sensitivity
- Whole word matching
- Column filtering
- Comprehensive results:
- Row IDs for matched rows
- Detailed match context
- Search statistics
- Metadata Handling
- Extracts and processes column metadata
- Handles validation rules
- Manages format specifications
- Tracks formula dependencies
- Maintains column relationships
- Healthcare Analytics
- Clinical note summarization using Azure OpenAI
- Patient feedback sentiment analysis
- Protocol compliance scoring
- Research impact assessment
- Resource utilization analysis
- Custom analysis with optimized prompt generation
- Batch Processing
- Automatic row batching (3 rows per batch for optimal performance)
- Progress tracking and monitoring
- Error handling and recovery
- Customizable processing goals
- Multi-column analysis support
- Token-aware content chunking for large text
- Background job processing with ThreadPoolExecutor
- Job Management
- Real-time status monitoring
- Detailed progress tracking
- Error reporting and logging
- Job cancellation support
- Batch operation controls
- Cross-Sheet References
- Formula analysis and dependency mapping
- Cross-sheet reference detection and validation
- Broken link identification and repair suggestions
- Automated formula generation (INDEX_MATCH, VLOOKUP, SUMIF, COUNTIF)
- Reference impact analysis across workspaces
- Custom formula template support
Setup
Prerequisites
- Node.js and npm
- Conda (for environment management)
- Smartsheet API access token
- Azure OpenAI API access (for batch analysis features)
Environment Setup
- Create a dedicated conda environment:
- Install Node.js dependencies:
- Install Python dependencies:
Note: The Python package includes dependencies for:
smartsheet-python-sdk
- Smartsheet API clientpython-dotenv
- Environment variable managementopenai
- Azure OpenAI integrationtiktoken
- Token counting for AI analysis
- Build the TypeScript server:
Configuration
The server supports two transport modes:
- STDIO Transport (default): For local development and CLI usage
- HTTP Transport: For web-based clients and network access
1. Get Your Smartsheet API Key
- Log in to Smartsheet
- Go to Account → Personal Settings → API Access
- Generate a new access token
2. Configure for STDIO Transport (Cline/Local)
The configuration path depends on your operating system:
macOS:
Windows:
Linux:
3. Configure for HTTP Transport
For web-based MCP clients or network access, use the HTTP transport mode:
Start the server:
Client Configuration:
Health Check:
The HTTP server provides a health check endpoint:
Starting the Server
STDIO Transport (Default)
The server will start automatically when Cline or Claude Desktop needs it. However, you can also start it manually for testing.
macOS/Linux:
Windows:
HTTP Transport
For web-based clients or network access:
macOS/Linux:
Windows:
Command Line Options
Verifying Installation
STDIO Transport
- The server should output "Smartsheet MCP server running on stdio" when started
- Test the connection using any MCP tool (e.g., get_column_map)
HTTP Transport
- The server should output "Smartsheet MCP server running on HTTP port 3000" when started
- Test the health endpoint:
curl http://localhost:3000/health
- Expected response:
{"status":"ok","server":"smartsheet-mcp"}
Python Environment
Check the Python environment has the required packages installed:
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
Usage Examples
Getting Column Information (Read)
Writing Data (Create)
Searching Data
Updating Data (Update)
Deleting Data (Delete)
Healthcare Analytics Examples
Workspace Management Examples
Resources Usage Examples
Prompts Usage Examples
Development
For development with auto-rebuild:
CI/CD Pipeline
This project implements a comprehensive 8-stage CI/CD pipeline with GitHub Actions, ensuring code quality, security, and reliability across all components.
Pipeline Architecture
The CI/CD pipeline consists of 8 coordinated jobs that run in parallel and sequence for optimal efficiency:
- TypeScript Quality Checks - ESLint, type checking, formatting validation
- Python Quality Checks - Black, Flake8, MyPy type checking
- TypeScript Testing - Matrix testing on Node.js 16, 18, 20 with coverage
- Python Testing - Matrix testing on Python 3.8, 3.9, 3.10, 3.11 with coverage
- Combined Coverage - Unified coverage reporting and Codecov integration
- Integration Testing - End-to-end validation and MCP server startup verification
- Security Scanning - npm audit, Python safety, Bandit security analysis
- Build and Package - Artifact creation and deployment verification
Key Pipeline Features
Quality Assurance:
- Multi-language Support: Full TypeScript and Python pipeline coverage
- Matrix Testing: Cross-platform compatibility verification
- Code Quality Gates: ESLint, Black, Flake8, MyPy, TypeScript strict mode
- Coverage Enforcement: Automated coverage threshold validation
- Security Scanning: Regular vulnerability assessment with safety and Bandit
Performance Optimization:
- Parallel Execution: Independent jobs run concurrently for faster feedback
- Intelligent Caching: Node modules and Python dependencies cached across runs
- Conditional Execution: Performance tests only on PRs, full coverage on main
- Artifact Management: Build artifacts preserved for 7-30 days
Integration and Deployment:
- MCP Protocol Validation: Server startup and protocol compliance testing
- Docker Support: Multi-platform container builds (linux/amd64, linux/arm64)
- Automated Releases: Version-tagged releases with changelog generation
- Dependency Management: Weekly security audits and update automation
Workflow Triggers
Status Monitoring
The pipeline provides comprehensive notifications and artifact management, ensuring all stakeholders have visibility into build status, test results, and deployment readiness.
Testing and Quality Assurance
This project maintains comprehensive test coverage and quality assurance across both TypeScript and Python components with automated CI/CD pipelines.
Test Infrastructure
Test Status: 54/54 TypeScript tests passing, 5/5 Python tests passing
Our comprehensive testing strategy includes:
- Unit Tests: Jest for TypeScript (54 tests), pytest for Python (5 core tests)
- Integration Tests: Cross-component testing and MCP protocol validation
- Code Quality: ESLint, TypeScript checking, Black, Flake8, MyPy
- Security Scanning: npm audit, Python safety checks, Bandit analysis
- Coverage Analysis: Combined coverage reporting with Codecov integration
- Performance Testing: Startup time measurement and benchmark tracking
Test Coverage Overview
Current coverage metrics:
- TypeScript Coverage: Comprehensive coverage of MCP server implementation
- Python Coverage: Core operations and CLI functionality
- Combined Reporting: Unified coverage analysis across both languages
- Automated Tracking: Real-time coverage monitoring via Codecov
Quick Testing Commands
Comprehensive Testing Commands
Test Reports and Artifacts
After running tests, detailed reports are available:
- TypeScript Coverage:
./coverage/index.html
- Python Coverage:
./smartsheet_ops/coverage/index.html
- Combined Coverage:
./coverage-combined/index.html
- Test Artifacts: Available in CI/CD pipeline runs
Quality Thresholds
The project enforces strict quality standards:
- TypeScript Coverage: 60% minimum (configurable per component)
- Python Coverage: 80% overall with line-by-line reporting
- Code Quality: ESLint rules, TypeScript strict mode, Python Black/Flake8
- Security: Regular dependency audits and vulnerability scanning
- Performance: Startup time monitoring and regression detection
Docker Support
Build and run the containerized version:
Debugging
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:
- Error logging to stderr
- Detailed error messages in MCP responses
- Type validation at multiple levels
- Comprehensive operation result reporting
- Dependency analysis for column operations
- Formula reference tracking
Error Handling
The server implements a multi-layer error handling approach:
- MCP Layer
- Validates tool parameters
- Handles protocol-level errors
- Provides formatted error responses
- Manages timeouts and retries
- CLI Layer
- Validates command arguments
- Handles execution errors
- Formats error messages as JSON
- Validates column operations
- Operations Layer
- Handles Smartsheet API errors
- Validates data types and formats
- Provides detailed error context
- Manages column dependencies
- Validates formula references
- Ensures data integrity
Contributing
Contributions are welcome! Please ensure:
- TypeScript/Python code follows existing style
- New features include appropriate error handling
- Changes maintain backward compatibility
- Updates include appropriate documentation
- Column operations maintain data integrity
- Formula references are properly handled
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
Provides seamless integration with Smartsheet, enabling automated operations on Smartsheet documents through a standardized interface that bridges AI-powered automation tools with Smartsheet's collaboration platform.
Related Resources
Related MCP Servers
- AsecurityAlicenseAqualityProvides integration with OpenRouter.ai, allowing access to various AI models through a unified interface.Last updated -2857Apache 2.0
- -securityAlicense-qualityEnables integration with Google Drive for listing, reading, and searching over files, supporting various file types with automatic export for Google Workspace files.Last updated -80046MIT License
- -securityAlicense-qualityIntegrates with Google Drive to enable listing, searching, and reading files, plus reading and writing to Google Sheets.Last updated -203187MIT License
- -securityFlicense-qualityIntegrates with Google Drive to enable listing, reading, and searching over files, with automatic export of Google Workspace documents to appropriate formats.Last updated -800