smartsuite_mcp_server

Grupo-AFAL/smartsuite_mcp_server

3.2

If you are the rightful owner of smartsuite_mcp_server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The SmartSuite MCP Server is a Model Context Protocol server designed to facilitate interaction between AI assistants and SmartSuite workspaces.

Tools
8
Resources
0
Prompts
0

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, supporting multiple users and API key authentication.

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

# SmartSuite credentials (can be per-user via API)
SMARTSUITE_API_KEY=your_api_key
SMARTSUITE_ACCOUNT_ID=your_account_id
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 for detailed instructions.

Get API Credentials

Before installation, get your SmartSuite credentials:

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

📚 Documentation

Getting Started

  • - Detailed setup instructions
  • - 5-minute walkthrough
  • - All environment variables and settings
  • - Common issues and solutions

Guides

  • - How to use the server with Claude
  • - Understanding the cache system
  • - Filter syntax and examples
  • - Optimization tips

API Reference

  • - Solutions and usage analysis
  • - Tables and schemas
  • - CRUD operations, bulk operations, file URLs, deleted records
  • - Schema management
  • - Users and teams

Architecture

  • - High-level architecture
  • - How caching works
  • - MCP implementation details
  • - 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 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:

🤝 Contributing

We welcome contributions! See for guidelines.

📋 Project Status

  • Current Version: 2.0.0
  • Ruby: 3.4.7
  • Rails: 8.1.1 (hosted mode)
  • Roadmap: See
  • Changelog: See

🐛 Support

📄 License

MIT License - see 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