SmartSuite MCP Server

A Model Context Protocol (MCP) server for SmartSuite that enables AI assistants like Claude to interact with your SmartSuite workspace through natural language.

✨ Features

Comprehensive SmartSuite API Coverage - Solutions, tables, records (including bulk operations), fields, members, comments, views, and deleted records management
Aggressive SQLite Caching - 12-hour TTL with cache-first strategy (75%+ API call reduction)
Token Optimization - TOON format responses and filtered structures (60%+ token savings)
Session Tracking - Monitor API usage by user, solution, table, and endpoint
Smart Filtering - Local SQL queries on cached data with SmartSuite filter syntax support
Dual Mode Operation - Run as stdio MCP server or hosted Rails API server

🚀 Quick Start

Option 1: Stdio MCP Server (Claude Desktop)

The traditional MCP server mode communicates via stdin/stdout with Claude Desktop.

One-Liner Installation (Easiest!)

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/Grupo-AFAL/smartsuite_mcp_server/main/bootstrap.sh | bash

# Windows (PowerShell)
irm https://raw.githubusercontent.com/Grupo-AFAL/smartsuite_mcp_server/main/bootstrap.ps1 | iex

That's it! The script will:

✅ Check for Git (required) and provide install instructions if needed
✅ Clone the repository to ~/.smartsuite_mcp
✅ Auto-install Homebrew on macOS (if needed)
✅ Auto-install Ruby via package manager (if needed)
✅ Install all dependencies
✅ Prompt for your SmartSuite API credentials
✅ Configure Claude Desktop automatically

Just restart Claude Desktop when done!

Alternative: Manual Clone + Script

# Clone the repository
git clone https://github.com/Grupo-AFAL/smartsuite_mcp_server.git
cd smartsuite_mcp_server

# Run the installation script
./install.sh          # macOS/Linux
.\install.ps1         # Windows

Option 2: Hosted Rails Server (Multi-User API)

The hosted mode runs as a Rails API server with PostgreSQL. It is an OAuth 2.1 authorization server, so Claude Desktop, Claude.ai and Claude Code connect to it directly as a Custom Connector and every user signs in with their own SmartSuite API key. No proxy and no app-issued keys are needed (legacy Bearer ss_... API keys still work). See Connecting Claude with OAuth.

Prerequisites

Ruby 3.4.7+
PostgreSQL
Redis (optional, for caching)

Setup

# Clone and install
git clone https://github.com/Grupo-AFAL/smartsuite_mcp_server.git
cd smartsuite_mcp_server
bundle install

# Setup database
bin/rails db:create db:migrate

# Start server
bin/rails server

Environment Variables

# Required for hosted mode
DATABASE_URL=postgres://user:pass@localhost/smartsuite_mcp
RAILS_MASTER_KEY=your_master_key

# Optional: pre-fill the Workspace ID on the OAuth sign-in page
SMARTSUITE_ACCOUNT_ID=your_account_id

Connect from Claude

Claude → Settings → Connectors → Add custom connector → paste https://your-server/mcp
Click Connect and sign in with your SmartSuite Workspace ID and API key
Organization admins can add the connector for everyone under Admin settings → Connectors;
bin/rails oauth:create_client NAME="Claude (Org)" prints a stable client ID/secret if you prefer one.

Deployment with Kamal

The server includes Kamal configuration for easy deployment:

# Copy example config
cp config/deploy.yml.example config/deploy.yml

# Edit with your settings
# - DEPLOY_SERVER_IP
# - DEPLOY_HOST
# - KAMAL_REGISTRY_USERNAME

# Deploy
kamal setup
kamal deploy

See Deployment Guide for detailed instructions.

Get API Credentials

Before installation, get your SmartSuite credentials:

Log in to SmartSuite
Go to Settings → API
Generate an API key and note your Account ID

📚 Documentation

Getting Started

Installation Guide - Detailed setup instructions
Quick Start Tutorial - 5-minute walkthrough
Configuration Options - All environment variables and settings
Troubleshooting - Common issues and solutions

Guides

User Guide - How to use the server with Claude
Caching Guide - Understanding the cache system
Filtering Guide - Filter syntax and examples
Performance Guide - Optimization tips

API Reference

Workspace Operations - Solutions and usage analysis
Table Operations - Tables and schemas
Record Operations - CRUD operations, bulk operations, file URLs, deleted records
Field Operations - Schema management
Member Operations - Users and teams
Complete API Documentation

Architecture

Overview - High-level architecture
Caching System - How caching works
MCP Protocol - MCP implementation details
Design Decisions - Why we made certain choices

💡 Examples

# List all solutions with usage metrics
list_solutions(include_activity_data: true)

# Get records with caching (uses local SQLite cache)
list_records('table_abc123', 10, 0, fields: ['status', 'priority'])

# Create a record
create_record('table_abc123', {
  'status' => 'Active',
  'priority' => 'High',
  'assigned_to' => ['user_xyz789']
})

# Refresh cache when needed
refresh_cache('records', table_id: 'table_abc123')

See examples/ for more usage patterns.

🧪 Testing

# Run all unit tests
bundle exec rake test

# Run integration tests (requires API credentials)
bundle exec rake test:integration

# Run with verbose output
bundle exec rake test TESTOPTS="-v"

🛠️ Utility Scripts

The server includes CLI utility scripts for administrative and batch operations:

Batch Markdown Converter

Convert multiple SmartSuite records from Markdown to SmartDoc format in bulk:

# Convert all webhook-generated records
bin/convert_markdown_sessions

# Dry-run to preview changes
bin/convert_markdown_sessions --dry-run --limit 10

Use Cases:

Automated webhook data (Read.ai meeting transcripts, etc.)
Bulk data formatting/migration
Scheduled transformation tasks

Documentation: Batch Markdown Conversion Guide

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

📋 Project Status

Current Version: 2.0.0
Ruby: 3.4.7
Rails: 8.1.3 (hosted mode)
Roadmap: See ROADMAP.md
Changelog: See CHANGELOG.md

🐛 Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Troubleshooting: See docs/getting-started/troubleshooting.md

📄 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

Built with the Model Context Protocol by Anthropic.

⚡ Performance Stats

Cache hit rate: >80% for metadata queries
API call reduction: >75% vs uncached
Token savings: >60% average per session
Response time: <100ms for cached queries