mcp-server-smartsheet-rm

mcp-server-smartsheet-rm

Enterprise Model Context Protocol (MCP) server for Resource Management by Smartsheet (10,000ft API).

Enables AI coding agents, planners, and assistants (Claude, Cortex, Antigravity, VS Code) to orchestrate the complete Smartsheet RM REST API surface: time tracking & timesheet reconciliation, resource scheduling & allocations, capacity planning, project & phase management, leaves/holidays, expense tracking, and custom fields.

⚡ Tool Surface Overview

The server exposes tools covering projects, resources, timesheets, and capacity:

• Default Registration: 98 tools (with bulk-destructive operations gated by default).
• With Bulk Operations: 100 total tools when SMARTSHEET_RM_ALLOW_BULK_DESTRUCTIVE=1.
• Read-Only Mode: 39 tools (readOnlyHint=true).
• Destructive Gates: 21 tools requiring explicit confirm=True (19 standard + 2 bulk).
• Idempotent Operations: 4 tools with idempotentHint=true.

Domain Breakdown

Counts below include the 2 bulk-destructive tools (100 total).

• Time Tracking & Approvals (8 tools): List/get/create/update/delete time entries, fetch suggestions, approve/reject hours, lock timesheets.
• Projects & Phases (11 tools): Full CRUD for projects, project users, milestones, budgets, and project phases.
• Assignments & Scheduling (5 tools): Full CRUD for resource assignments, percentages, fixed hours, and schedules.
• Users, Roles & Capacity (17 tools): User management, bill rate tiers, availability queries, utilization metrics, roles, and disciplines.
• Clients & Contacts (8 tools): Client organization CRUD and client contact records.
• Leaves & Holidays (10 tools): Vacation/PTO leave types, non-working days, and regional company holidays.
• Expense Tracking (8 tools): Expense submissions, category definitions, and billable tracking.
• Tags & Custom Fields (10 tools): Custom field definitions, field values, and tagging.
• Approvals, Statuses & Placeholders (9 tools): Organization approvals, user work status tracking (ITO/WFH/OOO/VAC), and placeholder resources.
• Subtasks, Reports & Webhooks (8 tools): Assignment task checklists, custom report generation (rows/totals), and event webhooks.
• Composite Workflow Recipes (6 tools): Bulk timesheet logging, auto-suggestion confirmation, 40h reconciliation audit, project schedule cloning, and bulk deletion.

🚀 Quickstart & Installation

1. Installation

# Using uv (recommended)
uv pip install mcp-server-smartsheet-rm

# Or standard pip
pip install mcp-server-smartsheet-rm

2. Environment Variables

Variable	Description	Default
SMARTSHEET_RM_API_TOKEN	Smartsheet RM (10,000ft) API Token (Required)	-
SMARTSHEET_RM_BASE_URL	Base API URL	https://api.rm.smartsheet.com/api/v1
SMARTSHEET_RM_PROFILE	Tool profile subset: time, projects, admin, full	full
SMARTSHEET_RM_READONLY	Set to 1 to restrict server to read-only tools	0
SMARTSHEET_RM_ALLOW_BULK_DESTRUCTIVE	Set to 1 to unlock bulk delete operations	0
SMARTSHEET_RM_LOG_FORMAT	Set to json for Datadog/CloudWatch structured logs	text

💻 Client Configurations

Google Antigravity (~/.gemini/antigravity-cli/mcp_config.json)

{
  "mcpServers": {
    "smartsheet-rm": {
      "command": "uvx",
      "args": ["mcp-server-smartsheet-rm"],
      "env": {
        "SMARTSHEET_RM_API_TOKEN": "your-api-token"
      },
      "lazy": true
    }
  }
}

Snowflake Cortex (~/.snowflake/cortex/mcp.json)

{
  "servers": {
    "smartsheet-rm": {
      "command": "uvx",
      "args": ["mcp-server-smartsheet-rm"],
      "env": {
        "SMARTSHEET_RM_API_TOKEN": "your-api-token"
      }
    }
  }
}

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "smartsheet-rm": {
      "command": "uvx",
      "args": ["mcp-server-smartsheet-rm"],
      "env": {
        "SMARTSHEET_RM_API_TOKEN": "your-api-token"
      }
    }
  }
}

🛡️ Safety & Reliability

• Secret Redaction: API tokens, bearer headers, and sensitive keys are automatically scrubbed from errors and logs.
• Destructive Gates: Every deletion tool declares confirm: bool = False and rejects execution unless the caller explicitly passes confirm=True.
• Profile Filtering: Minimize token footprint by loading only relevant tool sets (time, projects, admin).
• Resilience: Exponential backoff with randomized jitter on HTTP 429 rate limits.

🧪 Testing & Validation

# Run tests with 100% coverage requirement
pytest --cov=src/smartsheet_rm_mcp --cov-fail-under=100 -v

# Run Tool Contract verification
python scripts/check_tool_contract.py

# Run OpenAPI Drift check
python scripts/check_openapi_drift.py