npm package: @floomhq/mcp-server
Description: MCP server for Floom, lets AI agents deploy and run apps
Latest version: 0.1.8

# @floomhq/mcp-server

MCP server for Floom. Lets AI agents (Claude, Cursor) deploy and run Python apps.

## Setup

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "floom": {
      "command": "npx",
      "args": ["@floomhq/mcp-server"],
      "env": {
        "FLOOM_URL": "http://localhost:3001",
        "FLOOM_API_KEY": "your-api-key"
      }
    }
  }
}
```

### Cursor

Add to MCP settings with the same command and environment variables.

## Where deploy lands

**`FLOOM_URL` picks the Floom instance.** Use your **cloud** API base URL to deploy on **Floom’s servers** (no local Docker). Use `http://localhost:3001` (or your host) for **self-host**. **`FLOOM_API_KEY`** must match that same instance.

## Agent Workflow

**Env (required):** `FLOOM_URL` and `FLOOM_API_KEY` (same as control plane `API_KEY` when set). Example local: `http://localhost:3001`. Example cloud: `https://<your-cloud-api-host>` (exact value from your Floom cloud docs or dashboard).

1. Write Python with `@app.action` and type hints (floom derives OpenAPI; do not hand-author OpenAPI for apps)
2. `deploy(code, name)` -> project_id + slug + endpoint list
3. `run(slug, action, input)` -> result (synchronous, no polling needed)
4. `create_share_link(project_id)` -> public URL for anyone

Advanced:
- `manage_secrets()` -> set API keys before running
- `storage_set/get()` -> persist data across runs
- `create_schedule()` -> run on cron
- `deploy_from_github()` -> deploy from repo URL
- `promote/rollback()` -> version management

For the complete agent workflow guide, see [AGENT_GUIDE.md](https://github.com/floomhq/floom/blob/main/docs/AGENT_GUIDE.md).

## Tools (32 total)

### Core Workflow

- **deploy** - Deploy Python code with optional config and requirements
- **run** - Execute an endpoint by slug+action or project_id+endpoint_id (auto-polls until result)
- **list_projects** - List all deployed apps
- **get_project** - Get app details and endpoint schemas
- **delete_project** - Remove a project
- **update_project** - Update project name or slug

### Version Management

- **list_versions** - Show dev/prod versions with hashes
- **promote** - Promote a version to production with health check
- **rollback** - Rollback to a previous version

### Storage (persistent key-value)

- **storage_set** - Store a value (up to 10MB)
- **storage_get** - Retrieve a value by key
- **storage_delete** - Remove a key
- **storage_list** - List all keys for a project

### Secrets

- **manage_secrets** - Set, list, or delete encrypted API keys (action param)

### Share Links

- **create_share_link** - Generate a public URL
- **list_share_links** - List existing links
- **disable_share_link** - Revoke a share link

### Context (project metadata)

- **fetch_context** - Pull context from a URL
- **get_context** - Get a stored context
- **list_contexts** - List all contexts
- **delete_context** - Remove a context
- **refresh_context** - Re-fetch a context from its URL

### Scheduling

- **create_schedule** - Set up cron-based execution
- **list_schedules** - List schedules for a project
- **delete_schedule** - Remove a schedule

### Templates

- **list_templates** - Browse starter templates
- **get_template** - Get template details and code
- **create_from_template** - Create a project from a template

### GitHub

- **deploy_from_github** - Deploy directly from a GitHub repo URL

### Webhooks

- **enable_webhooks** - Enable inbound webhook triggers
- **disable_webhooks** - Disable webhooks

### Logs

- **get_logs** - View recent execution logs with error details and suggested fixes

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `FLOOM_URL` | Yes | Floom server URL |
| `FLOOM_API_KEY` | No | API key (optional in OSS mode) |

## License

MIT