smartsuite_mcp_server

A Model Context Protocol (MCP) server for SmartSuite, enabling AI assistants to interact with your SmartSuite workspace.

Installation

Run this command in your terminal to add the MCP server to Claude Code.

Run in terminal:

View docs

Command

claude mcp add --transport stdio grupo-afal-smartsuite_mcp_server docker run -i grupo-afal/smartsuite_mcp_server \
  --env DATABASE_URL="postgres://user:pass@localhost/smartsuite_mcp" \
  --env VERBOSE_LOGGING="true" \
  --env RAILS_MASTER_KEY="your_master_key" \
  --env SMARTSUITE_API_KEY="your_api_key" \
  --env SMARTSUITE_ACCOUNT_ID="your_account_id"

How to use

SmartSuite MCP Server exposes two operational modes: a stdio-based MCP server for local, direct integration with Claude Desktop, and a hosted Rails API server for multi-user access. In stdio mode, the MCP server communicates over standard input and output, enabling Claude or other clients to send natural language prompts that are parsed into SmartSuite workspace operations such as listing solutions, reading or updating records, and applying filters. The hosted Rails server provides a fully-fledged API with per-user authentication, PostgreSQL persistence, and optional Redis caching. You can choose the mode that best fits your deployment constraints and security requirements. The system includes comprehensive documentation on workspace, table, record, field, and member operations, as well as guidance on caching, filtering, and performance tuning. The CLI utility scripts also offer batch processing tools to transform data and manage Markdown conversions, which can be integrated into your automation pipelines.

How to install

Prerequisites:

Ruby 3.4.7+ and Rails 8.1.1+ for hosted Rails API mode
PostgreSQL (and Redis optional) for hosted mode
Docker (for containerized deployment) or a Ruby runtime if you prefer native Rails execution

Option A: Run as Hosted Rails API (local development)

Clone the repository git clone https://github.com/Grupo-AFAL/smartsuite_mcp_server.git
Change into the project directory cd smartsuite_mcp_server
Install dependencies bundle install
Configure the database bin/rails db:create db:migrate
Start the server bin/rails server
Set environment variables (example) DATABASE_URL=postgres://user:pass@localhost/smartsuite_mcp RAILS_MASTER_KEY=your_master_key SMARTSUITE_API_KEY=your_api_key SMARTSUITE_ACCOUNT_ID=your_account_id

Option B: Run as Stdio MCP Server (Claude Desktop) using Docker

Ensure Docker is installed on your machine
Pull and run the container (example) docker run -it --rm -e SMARTSUITE_API_KEY=your_api_key -e SMARTSUITE_ACCOUNT_ID=your_account_id -e DATABASE_URL=postgres://user:pass@localhost/smartsuite_mcp -e RAILS_MASTER_KEY=your_master_key grupo-afal/smartsuite_mcp_server
Connect Claude Desktop to the stdio MCP interface as documented in the project

Option C: Quick start via one-liner (if you prefer scripts)

Run the one-liner bootstrap script for stdio mode or follow the manual installation steps in the README to install Ruby and dependencies.

Additional notes

Tips and common considerations:\n- In hosted mode, ensure your DATABASE_URL is reachable from the Rails server and that API key credentials are kept secret.\n- The project includes extensive documentation on API endpoints for workspace, tables, records, fields, and members.\n- If you enable caching (Redis), monitor cache hit rates to balance performance with data freshness.\n- For deployment, Kamal configuration is provided in the README to simplify remote hosting; adjust deploy.yml settings to your environment.\n- The stdio mode is ideal for local testing with Claude Desktop, while the hosted Rails mode supports multi-user access and API key-based authentication.\n- When upgrading Ruby or Rails, consult the CHANGELOG and ROADMAP to address breaking changes or migration steps.