home / mcp / bubble mcp server

Bubble MCP Server

A Model Context Protocol server that enables AI assistants to read and manipulate Bubble.io data through a secure, type-safe interface.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "dorianglz-bubble_mcp": {
      "command": "node",
      "args": [
        "dist/mcp-server.js"
      ],
      "env": {
        "MCP_MODE": "read-only",
        "BUBBLE_BASE_URL": "https://your-app.bubbleapps.io",
        "BUBBLE_API_TOKEN": "your-bubble-api-token-here"
      }
    }
  }
}

You can connect AI assistants and MCP-compatible clients to your Bubble.io apps through a standardized MCP server. This server lets you read, create, update, delete, and run workflows against Bubble data while respecting privacy rules and providing clear type information.

How to use

Once your Bubble MCP server is running, configure your MCP client to point at the local or remote server. You can perform common data actions such as listing data types, fetching records, creating new records, updating existing ones, deleting records, and running Bubble API workflows. Start in read-only mode to explore your app structure and data, then switch to read-write only when you need to modify data or run workflows.

How to install

Prerequisites you need before installing: Node.js (v16 or higher), npm or yarn, and a Bubble.io application with API access enabled.

Local development setup for Mac/Linux and Windows is provided with a standard clone, install, and build flow.

# Mac/Linux
git clone https://github.com/nocoderoi/bubble_mcp.git
cd bubble_mcp
npm install
cp .env.example .env
# Edit .env with your Bubble app details
npm run build

# Windows
git clone https://github.com/nocoderoi/bubble_mcp.git
cd bubble_mcp
npm install
copy .env.example .env
# Edit .env with your Bubble app details
npm run build

Configuration

You configure access to your Bubble app by providing a Bubble API token and setting the required environment variables.

Getting your Bubble API token and setting up the MCP mode are described here so you can control what the MCP server can do.

Security and best practices

The MCP server supports two modes: read-only and read-write. Start with read-only to safely explore data and app structure, then move to read-write only when you need to modify data or run workflows.

Follow safety guidelines: use separate tokens for read-only and read-write access, keep tokens secure, and document changes for audit.

Troubleshooting

Common issues include authentication failures, privacy rule violations, and connectivity problems. Verify that your Bubble Data API is enabled, your API token has the correct permissions, and the MCP server process is running with the correct environment variables.

Notes

If you need to run the server in development mode with hot-reloading, you can use the development command provided in the setup steps. Always ensure your environment variables are set correctly in your runtime environment.

Starting the server in runtime

# Direct Node Execution
node dist/mcp-server.js

# Development Mode (with hot-reloading)
npm run mcp

Available tools

List Data Types

Query the server to enumerate all data types available in your Bubble app, including their fields and relationships.

Fetch Records

Retrieve records from a specific data type with optional filtering, pagination, and sorting.

Create Records

Create new records for a data type with the required fields and validation rules.

Update Records

Modify existing records by ID or other identifiers, applying updates to specified fields.

Delete Records

Remove records from a data type by identifier with safety checks.

Execute Workflows

Trigger API workflows defined in your Bubble app for specific records or conditions.

Privacy Rules Respect

Operate within Bubble’s privacy constraints to prevent unauthorized data access.