butterbase

# Butterbase **AI-native, open-source backend-as-a-service** with a built-in Model Context Protocol (MCP) server. Postgres data plane, auth, storage, serverless functions, AI gateway, RAG, realtime, and durable objects — all drivable by an AI agent via MCP tools. This repo ships the open-source runtime. The managed offering at [butterbase.ai](https://butterbase.ai) adds multi-region orchestration, billing, and ops. ## What the MCP server can do Nearly 40 tools across the platform's surface area, including: - **Apps & regions** — `init_app`, `manage_app` (actions: list/delete/pause/get_config/update_access_mode/secure/update_cors/set_visibility/preview_clone_env_vars/clone/get_clone_job/find_templates/set_clone_webhook/link_substrate/unlink_substrate/move/move_status/teardown_source_replica), `list_regions` - **Schema** — `manage_schema` (declarative DSL, dry-run diffs), `manage_migrations` - **Auth** — `manage_auth_config`, `manage_auth_users`, `manage_oauth` - **Data** — `select_rows`, `insert_row`, `seed_database` - **Functions** — `deploy_function`, `invoke_function`, `manage_function` - **Storage** — `manage_storage` (presigned URLs, ACLs) - **Frontends** — `create_frontend_deployment`, `manage_frontend`, `manage_edge_ssr` - **RAG** — `manage_rag_content`, `rag_query` - **Realtime & Durable Objects** — `manage_realtime`, `manage_durable_objects` - **AI gateway** — `manage_ai` (chat, embeddings, BYOK) - **Row-Level Security** — `manage_rls` - **Integrations** — `manage_integrations` (Composio: email, Slack, GitHub, Notion, Linear, CRM) - **Billing** — `manage_billing` (Stripe Connect) - **KV, API keys, audit logs**, and more ## Install ### Option 1 — Claude Code plugin (recommended) ```bash claude plugin marketplace add https://github.com/butterbase-ai/butterbase-skills claude plugin install butterbase-skills@butterbase-skills ``` Plugin includes 39 guided skills and 34 slash commands (`/butterbase-skills:journey`, `/butterbase-skills:build-app`, …) and auto-configures the MCP server. ### Option 2 — Hosted MCP (any client) Add to your MCP config: ```json { "mcpServers": { "butterbase": { "url": "https://api.butterbase.ai/mcp", "headers": { "Authorization": "Bearer ${BUTTERBASE_API_KEY}" } } } } ``` ### Option 3 — Local stdio MCP ```bash npx @butterbase/mcp ``` Or wire it up in your MCP config: ```json { "mcpServers": { "butterbase": { "command": "npx", "args": ["-y", "@butterbase/mcp"], "env": { "BUTTERBASE_API_KEY": "bb_sk_..." } } } } ``` ### Option 4 — Self-host the whole stack See the [Quickstart](./README.md#quickstart-self-host) in `README.md`. Requires Docker + Node 22+. ## Get an API key Sign up at [butterbase.ai](https://butterbase.ai) and generate a key, or self-host and use the CLI: ```bash butterbase keys generate ``` Keys are prefixed `bb_sk_…`. ## Supported AI assistants Any MCP-capable client works. Tested with: **Claude Code**, **Claude Desktop**, **Cursor**, **Windsurf**, **Codex CLI**. ## Related - **[@butterbase/mcp](https://www.npmjs.com/package/@butterbase/mcp)** — stdio MCP server (this repo, installable from npm) - **[butterbase-skills](https://github.com/butterbase-ai/butterbase-skills)** — Claude Code plugin with 39 guided skills and 34 slash commands - **[@butterbase/sdk](https://www.npmjs.com/package/@butterbase/sdk)** — TypeScript SDK - **[@butterbase/cli](https://www.npmjs.com/package/@butterbase/cli)** — local dev / scaffolding CLI ## License Apache-2.0 ## Optional video reference preparation For explicitly declared AI-generated fictional characters, follow [bundled AI command guidance](docs/plugin-ai-command.md). Use `reference_declarations` only when supplied or established by the caller, and choose `prepare_references: "on_rejection"` (default) or `"upfront"`. Keep the same job ID through preparation and settlement. Do not infer consent or retry an uncertain paid submission. Preparation sends image bytes to a provider for storage; explain the retention behavior in the linked guide.