Bubble MCP

A Model Context Protocol (MCP) server that enables AI assistants and other MCP-compatible clients to interact with Bubble.io applications. This server provides a standardized interface for reading and manipulating data in any Bubble application.

🚀 Features

Universal Bubble Support: Works with any Bubble.io application
Auto-discovery: Automatically discovers your app's data types and structure
CRUD Operations: Create, Read, Update, and Delete operations for all data types
Workflow Execution: Execute API workflows defined in your Bubble app
Privacy Settings Aware: Respects Bubble's privacy rules and constraints
Read-only/Read-write Modes: Configurable access levels for safety
Type-safe: Provides detailed type information for all operations

🔌 MCP Compatibility

This server implements the Model Context Protocol (MCP), an open protocol that enables secure, standardized communication between AI assistants and external systems. While MCP was developed by Anthropic, it's designed to be vendor-agnostic.

Currently Compatible Clients:

Claude Desktop - Full support
Other MCP clients - Should work with any client that implements the MCP specification

Future Compatibility:

As MCP is an open protocol, we expect more AI assistants and tools to add support over time. This server will work with any client that properly implements the MCP standard.

📋 Prerequisites

Node.js (v16 or higher)
npm or yarn
A Bubble.io application with API access enabled
An MCP-compatible client (e.g., Claude Desktop)

🛠️ Installation

Local Development Setup

For Mac/Linux:

Clone the repository:

git clone https://github.com/nocoderoi/bubble_mcp.git
cd bubble_mcp

Install dependencies:
```
npm install
```
Copy the example environment file:
```
cp .env.example .env
```

Edit .env with your Bubble app details:

nano .env  # or use your preferred text editor

Build the project:
```
npm run build
```

For Windows:

Clone the repository:

git clone https://github.com/nocoderoi/bubble_mcp.git
cd bubble_mcp

Install dependencies:
```
npm install
```
Copy the example environment file:
```
copy .env.example .env
```

Edit .env with your Bubble app details:

notepad .env

Or use any text editor to add:

BUBBLE_BASE_URL=https://your-app.bubbleapps.io
BUBBLE_API_TOKEN=your-bubble-api-token-here
MCP_MODE=read-write  # Options: read-only, read-write

Build the project:
```
npm run build
```

🔧 Configuration

Getting Your Bubble API Token

Go to your Bubble app editor
Navigate to Settings → API
Enable "This app exposes a Data API"
Generate an API token
Copy the token to your .env file

Setting Up Your MCP Client

The exact configuration steps depend on your MCP client. Below are examples for Claude Desktop:

Claude Desktop Configuration

For Mac/Linux:

Copy the example configuration:

cp claude-desktop-config.example.json claude-desktop-config.json

Edit claude-desktop-config.json with your absolute path:

pwd  # Get your current directory path
nano claude-desktop-config.json

Update the configuration (example for Mac/Linux):

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

Copy to Claude Desktop config location:

cp claude-desktop-config.json ~/Library/Application\ Support/Claude/claude_desktop_config.json

For Windows:

Copy the example configuration:

copy claude-desktop-config.example.json claude-desktop-config.json

Get your current directory path:
```
cd
```

Edit claude-desktop-config.json with the full Windows path:

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

Note: Use double backslashes (\\) in the path!

Copy to Claude Desktop config location:

copy claude-desktop-config.json %APPDATA%\Claude\claude_desktop_config.json

Restart Claude Desktop

Other MCP Clients

For other MCP-compatible clients, refer to their documentation for configuration instructions. The key configuration elements you'll need are:

Command: node
Arguments: Path to dist/mcp-server.js
Environment variables: BUBBLE_BASE_URL, BUBBLE_API_TOKEN, and MCP_MODE

🎯 Usage

Once configured, you can interact with your Bubble app through your MCP client:

Available Commands

List Data Types: "Show me all data types in my Bubble app"
Fetch Records: "Get all users from my database"
Create Records: "Create a new user with name 'John Doe'"
Update Records: "Update user with ID xxx to set email to 'new@email.com'"
Delete Records: "Delete the product with ID xxx"
Execute Workflows: "Run the 'send_welcome_email' workflow for user xxx"

🎥 Video Example

Watch a video demonstration of how to use the Bubble MCP integration with Claude Desktop:

Example Interactions

You: "List all the data types in my Bubble app"
Assistant: I'll help you discover the data types in your Bubble app...

You: "Show me the first 5 customers"
Assistant: I'll fetch the first 5 customers from your database...

You: "Create a new product called 'Widget' with price 29.99"
Assistant: I'll create a new product for you...

🔒 Security Considerations

Understanding MCP Modes

The Bubble MCP server supports two operational modes that control what actions the MCP client can perform:

🔍 Read-Only Mode (Recommended)

What it does: Only allows viewing and fetching data from your Bubble app
Available operations:
- List data types
- Fetch records
- View app structure
Blocked operations: Create, Update, Delete, and Workflow execution
When to use:
- When exploring your data
- For reporting and analysis
- When learning about your app structure
- As your default setting for safety

✏️ Read-Write Mode

What it does: Allows full CRUD operations and workflow execution
Available operations: All read operations PLUS:
- Create new records
- Update existing records
- Delete records
- Execute API workflows
When to use:
- Only when you specifically need to modify data
- For automation tasks
- During active development

🛡️ Best Practices for Safety

Start with Read-Only: Always begin with MCP_MODE=read-only in your configuration
```
"env": {
  "MCP_MODE": "read-only"  // Safe default
}
```
Temporary Write Access: Only switch to read-write when you need to perform modifications
```
"env": {
  "MCP_MODE": "read-write"  // Use with caution
}
```
Separate Configurations: Consider having two MCP server configurations:
- bubble-readonly: Your default for everyday use
- bubble-write: Only for when modifications are needed
API Token Permissions:
- Create separate API tokens with different permission levels
- Use restricted tokens for read-only access
- Keep write-enabled tokens extra secure

⚠️ Mode Differences at a Glance

Feature	Read-Only	Read-Write
List data types	✅	✅
Fetch records	✅	✅
Create records	❌	✅
Update records	❌	✅
Delete records	❌	✅
Execute workflows	❌	✅
Risk of data loss	None	Possible
Recommended for beginners	✅	❌

🔐 Additional Security Tips

API Tokens: Never commit your API tokens to version control
Environment Variables: Always use environment variables or secure configuration for sensitive data
Privacy Rules: The server respects Bubble's privacy rules - ensure your API token has appropriate permissions
Audit Trail: In read-write mode, keep track of changes made through the MCP server
Backup: Always backup your Bubble data before using read-write mode for bulk operations

🤝 Contributing

We welcome contributions from the community! Here's how you can help:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Guidelines

Write clear, commented code
Add tests for new features
Update documentation as needed
Follow the existing code style
Test with different Bubble app configurations

🐛 Troubleshooting

Common Issues

"Cannot find data type": Ensure your Bubble app has the Data API enabled
"Authentication failed": Check your API token is correct and has appropriate permissions
"Privacy rule violation": Your API token may not have access to certain data types
MCP client not connecting: Ensure the path in config is absolute and the server is built

Starting the Server

To start the MCP server, use one of the following commands depending on your environment:

For Direct Node Execution:

node dist/mcp-server.js

For Development Mode (with hot-reloading):

npm run mcp

Debug Mode

Set DEBUG=true in your environment to enable verbose logging:

Mac/Linux:

DEBUG=true npm run mcp

Windows (Command Prompt):

set DEBUG=true && npm run mcp

Windows (PowerShell):

$env:DEBUG="true"; npm run mcp

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

Made with ❤️ by the community

Bubble MCP

🚀 Features

Universal Bubble Support: Works with any Bubble.io application
Auto-discovery: Automatically discovers your app's data types and structure
CRUD Operations: Create, Read, Update, and Delete operations for all data types
Workflow Execution: Execute API workflows defined in your Bubble app
Privacy Settings Aware: Respects Bubble's privacy rules and constraints
Read-only/Read-write Modes: Configurable access levels for safety
Type-safe: Provides detailed type information for all operations

🔌 MCP Compatibility

Currently Compatible Clients:

Claude Desktop - Full support
Other MCP clients - Should work with any client that implements the MCP specification

Future Compatibility:

As MCP is an open protocol, we expect more AI assistants and tools to add support over time. This server will work with any client that properly implements the MCP standard.

📋 Prerequisites

Node.js (v16 or higher)
npm or yarn
A Bubble.io application with API access enabled
An MCP-compatible client (e.g., Claude Desktop)

🛠️ Installation

Local Development Setup

For Mac/Linux:

Clone the repository:

git clone https://github.com/nocoderoi/bubble_mcp.git
cd bubble_mcp

Install dependencies:
```
npm install
```
Copy the example environment file:
```
cp .env.example .env
```

Edit .env with your Bubble app details:

nano .env  # or use your preferred text editor

Build the project:
```
npm run build
```

For Windows:

Clone the repository:

git clone https://github.com/nocoderoi/bubble_mcp.git
cd bubble_mcp

Install dependencies:
```
npm install
```
Copy the example environment file:
```
copy .env.example .env
```

Edit .env with your Bubble app details:

notepad .env

Or use any text editor to add:

BUBBLE_BASE_URL=https://your-app.bubbleapps.io
BUBBLE_API_TOKEN=your-bubble-api-token-here
MCP_MODE=read-write  # Options: read-only, read-write

Build the project:
```
npm run build
```

🔧 Configuration

Getting Your Bubble API Token

Go to your Bubble app editor
Navigate to Settings → API
Enable "This app exposes a Data API"
Generate an API token
Copy the token to your .env file

Setting Up Your MCP Client

The exact configuration steps depend on your MCP client. Below are examples for Claude Desktop:

Claude Desktop Configuration

For Mac/Linux:

Copy the example configuration:

cp claude-desktop-config.example.json claude-desktop-config.json

Edit claude-desktop-config.json with your absolute path:

pwd  # Get your current directory path
nano claude-desktop-config.json

Update the configuration (example for Mac/Linux):

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

Copy to Claude Desktop config location:

cp claude-desktop-config.json ~/Library/Application\ Support/Claude/claude_desktop_config.json

For Windows:

Copy the example configuration:

copy claude-desktop-config.example.json claude-desktop-config.json

Get your current directory path:
```
cd
```

Edit claude-desktop-config.json with the full Windows path:

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

Note: Use double backslashes (\\) in the path!

Copy to Claude Desktop config location:

copy claude-desktop-config.json %APPDATA%\Claude\claude_desktop_config.json

Restart Claude Desktop

Other MCP Clients

For other MCP-compatible clients, refer to their documentation for configuration instructions. The key configuration elements you'll need are:

Command: node
Arguments: Path to dist/mcp-server.js
Environment variables: BUBBLE_BASE_URL, BUBBLE_API_TOKEN, and MCP_MODE

🎯 Usage

Once configured, you can interact with your Bubble app through your MCP client:

Available Commands

List Data Types: "Show me all data types in my Bubble app"
Fetch Records: "Get all users from my database"
Create Records: "Create a new user with name 'John Doe'"
Update Records: "Update user with ID xxx to set email to 'new@email.com'"
Delete Records: "Delete the product with ID xxx"
Execute Workflows: "Run the 'send_welcome_email' workflow for user xxx"

🎥 Video Example

Watch a video demonstration of how to use the Bubble MCP integration with Claude Desktop:

Example Interactions

You: "List all the data types in my Bubble app"
Assistant: I'll help you discover the data types in your Bubble app...

You: "Show me the first 5 customers"
Assistant: I'll fetch the first 5 customers from your database...

You: "Create a new product called 'Widget' with price 29.99"
Assistant: I'll create a new product for you...

🔒 Security Considerations

Understanding MCP Modes

The Bubble MCP server supports two operational modes that control what actions the MCP client can perform:

🔍 Read-Only Mode (Recommended)

What it does: Only allows viewing and fetching data from your Bubble app
Available operations:
- List data types
- Fetch records
- View app structure
Blocked operations: Create, Update, Delete, and Workflow execution
When to use:
- When exploring your data
- For reporting and analysis
- When learning about your app structure
- As your default setting for safety

✏️ Read-Write Mode

What it does: Allows full CRUD operations and workflow execution
Available operations: All read operations PLUS:
- Create new records
- Update existing records
- Delete records
- Execute API workflows
When to use:
- Only when you specifically need to modify data
- For automation tasks
- During active development

🛡️ Best Practices for Safety

Start with Read-Only: Always begin with MCP_MODE=read-only in your configuration
```
"env": {
  "MCP_MODE": "read-only"  // Safe default
}
```
Temporary Write Access: Only switch to read-write when you need to perform modifications
```
"env": {
  "MCP_MODE": "read-write"  // Use with caution
}
```
Separate Configurations: Consider having two MCP server configurations:
- bubble-readonly: Your default for everyday use
- bubble-write: Only for when modifications are needed
API Token Permissions:
- Create separate API tokens with different permission levels
- Use restricted tokens for read-only access
- Keep write-enabled tokens extra secure

⚠️ Mode Differences at a Glance

Feature	Read-Only	Read-Write
List data types	✅	✅
Fetch records	✅	✅
Create records	❌	✅
Update records	❌	✅
Delete records	❌	✅
Execute workflows	❌	✅
Risk of data loss	None	Possible
Recommended for beginners	✅	❌

🔐 Additional Security Tips

API Tokens: Never commit your API tokens to version control
Environment Variables: Always use environment variables or secure configuration for sensitive data
Privacy Rules: The server respects Bubble's privacy rules - ensure your API token has appropriate permissions
Audit Trail: In read-write mode, keep track of changes made through the MCP server
Backup: Always backup your Bubble data before using read-write mode for bulk operations

🤝 Contributing

We welcome contributions from the community! Here's how you can help:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Guidelines

Write clear, commented code
Add tests for new features
Update documentation as needed
Follow the existing code style
Test with different Bubble app configurations

🐛 Troubleshooting

Common Issues

"Cannot find data type": Ensure your Bubble app has the Data API enabled
"Authentication failed": Check your API token is correct and has appropriate permissions
"Privacy rule violation": Your API token may not have access to certain data types
MCP client not connecting: Ensure the path in config is absolute and the server is built

Starting the Server

To start the MCP server, use one of the following commands depending on your environment:

For Direct Node Execution:

node dist/mcp-server.js

For Development Mode (with hot-reloading):

npm run mcp

Debug Mode

Set DEBUG=true in your environment to enable verbose logging:

Mac/Linux:

DEBUG=true npm run mcp

Windows (Command Prompt):

set DEBUG=true && npm run mcp

Windows (PowerShell):

$env:DEBUG="true"; npm run mcp

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

Made with ❤️ by the community