@selibiks/bubble-mcp

MCP server for Bubble.io with 28 tools across 3 layers — query data, audit schemas, seed test records, and more.

Quick Start

# Install dependencies
npm install

# Build
npm run build

# Start (requires configuration — see below)
npm start

Configuration

Environment Variables

BUBBLE_APP_URL=https://your-app.bubbleapps.io
BUBBLE_API_TOKEN=your-api-token-here
BUBBLE_MODE=read-only
BUBBLE_ENVIRONMENT=development
BUBBLE_RATE_LIMIT=60

Variable	Required	Default	Description
BUBBLE_APP_URL	Yes	—	Your Bubble.io app URL
BUBBLE_API_TOKEN	Yes	—	API token from Bubble.io Settings > API
BUBBLE_MODE	No	read-only	read-only, read-write, or admin
BUBBLE_ENVIRONMENT	No	development	development or live
BUBBLE_RATE_LIMIT	No	60	Max requests per minute

Config File Alternative

Create bubble.config.json in the project root:

{
  "app_url": "https://your-app.bubbleapps.io",
  "api_token": "your-api-token-here",
  "mode": "read-only",
  "environment": "development",
  "rate_limit": 60
}

Environment variables take priority over the config file.

Claude Desktop / Claude Code Integration

Add to your Claude configuration:

{
  "mcpServers": {
    "bubble": {
      "command": "node",
      "args": ["/path/to/bubble-mcp/dist/index.js"],
      "env": {
        "BUBBLE_APP_URL": "https://your-app.bubbleapps.io",
        "BUBBLE_API_TOKEN": "your-api-token-here",
        "BUBBLE_MODE": "read-only",
        "BUBBLE_ENVIRONMENT": "development"
      }
    }
  }
}

Or via the CLI:

claude mcp add bubble -- node /path/to/bubble-mcp/dist/index.js

Security Model

Three-layer defence in depth:

Layer	What it does
Server Mode Gate	Filters tools by mode at startup (read-only < read-write < admin)
MCP Permissions	Claude prompts user approval before each tool invocation
Bubble Privacy Rules	Bubble.io enforces API-level access via the token's permissions

Input validation: All user-supplied identifiers (dataType, id, sort_field, workflow_name) are validated against safe character patterns before reaching API URLs. File paths (TDD tools) are sandboxed to the project directory.

Token safety: The API token is never exposed in responses or error messages. The bubble_get_environment tool explicitly excludes it.

Mode Reference

Capability	read-only	read-write	admin
Query data (search, get)	Yes	Yes	Yes
Inspect schema / Swagger docs	Yes	Yes	Yes
Create / update records	No	Yes	Yes
Trigger workflows	No	Yes	Yes
Delete records	No	No	Yes
Bulk operations	No	No	Yes
Seed / cleanup test data	No	No	Yes

Tool Reference (28 tools)

Core Tools (11)

Tool	Mode	Description
bubble_get_schema	read-only	Fetch the full app schema (all types and fields) from /meta
bubble_search	read-only	Search records with constraints, sorting, and pagination
bubble_get	read-only	Fetch a single record by type and ID
bubble_create	read-write	Create a new record
bubble_update	read-write	Partially update a record (PATCH)
bubble_replace	read-write	Replace a record entirely (PUT)
bubble_delete	admin	Permanently delete a record
bubble_bulk_create	admin	Create up to 1000 records in one call
bubble_trigger_workflow	read-write	Trigger a backend API workflow by name
bubble_get_environment	read-only	Return current server config (mode, environment, rate limit)
bubble_swagger_docs	read-only	Fetch the Swagger/OpenAPI spec for the connected app

Compound Tools (7)

Tool	Mode	Description
bubble_schema_summary	read-only	Type counts, relationships, and totals (lightweight vs full schema)
bubble_privacy_audit	read-only	Scan schema for sensitive fields, PII, and API write exposure
bubble_find_orphans	read-only	Find records with broken foreign key references
bubble_record_validator	read-only	Sample records and check for empty/null fields
bubble_search_all	read-only	Auto-paginate through all records of a type (up to 10k)
bubble_field_usage	read-only	Analyse field population rates and identify dead fields
bubble_compare_environments	read-only	Diff schemas between development and live environments

Developer Tools (10)

Tool	Mode	Description
bubble_health_check	read-only	Privacy audit + dead field detection with a 0-100 score
bubble_export_schema	read-only	Export schema as TDD-format markdown
bubble_workflow_map	read-only	List all API workflows and their parameters
bubble_tdd_validate	read-only	Validate a TDD markdown file against the live schema
bubble_migration_plan	read-only	Generate ordered migration steps from a TDD file
bubble_wu_estimate	read-only	Estimate Workload Units for a Bubble operation
bubble_suggest_indexes	read-only	Suggest fields that would benefit from indexes
bubble_option_set_audit	read-only	Find text fields that should be option sets
bubble_seed_data	admin	Seed test data in dependency order (tracked for cleanup)
bubble_cleanup_test_data	admin	Delete all previously seeded test data

Swagger / OpenAPI

The bubble_swagger_docs tool fetches the auto-generated Swagger spec from your Bubble app:

https://your-app.bubbleapps.io/api/1.1/meta/swagger.json

If you get an error, enable Swagger docs in Bubble: Settings > API > Enable Swagger documentation.

Development

npm install          # Install dependencies
npm run dev          # Development mode (tsx, no build needed)
npm run build        # Compile TypeScript to dist/
npm test             # Run all tests (179 tests)
npm run test:watch   # Tests in watch mode
npm run lint         # ESLint
npm run format       # Prettier
npm run typecheck    # tsc --noEmit

Defaults

Setting	Default	Why
Mode	read-only	Safe — no mutations possible
Environment	development	Safe — won't touch production
Rate limit	60 req/min	Prevents API abuse

License

MIT