Skip to main content
Glama
Flowdesk MCP

Flowdesk MCP

README.md
# Flowdesk MCP

A free, local-first alternative for Pabbly Connect-style workflows. Receive a JSON event, filter it, transform fields, save a record and forward the result to an HTTPS receiver. Build the same workflow in a browser or through an MCP client. The editor, webhook handler and MCP server share a SQLite database.

## Run the editor

Use Python 3.11 or newer. From a terminal:

```sh
git clone https://github.com/akash-decoder/flowdesk-mcp.git
cd flowdesk-mcp
python -m venv .venv
```

Activate the environment with `source .venv/bin/activate` on macOS/Linux or `.venv\Scripts\activate.bat` in Windows Command Prompt. Then run:

```sh
python -m pip install .
flowdesk web
```

Open **http://127.0.0.1:8765**. The initial **Lead intake** draft accepts website inquiries, builds a subject line and stores the transformed record. Choose **Save workflow**, then **Preview**. The sample produces `Quote request from Alex`. Choose **Run now** and open **Records** to see the saved result. Change `service` to `print` and run again to see a filtered event in **Run history**.

## Connect an MCP client

For a desktop client that supports stdio, add this entry to its MCP server configuration. Replace the command with the absolute path to the installed Python interpreter. On Windows use a path such as `C:/projects/flowdesk-mcp/.venv/Scripts/python.exe`. Restart the client after saving.

```json
{
  "mcpServers": {
    "flowdesk": {
      "command": "/absolute/path/to/flowdesk-mcp/.venv/bin/python",
      "args": ["-m", "flowdesk", "mcp"]
    }
  }
}
```

Try asking your client:

> Find my Lead intake workflow. Preview it with name Alex and service website. Show me the transformed record.

| Tool | Operation |
| --- | --- |
| `list_workflows` | Read definitions, IDs and revisions |
| `create_workflow` | Create a named workflow with ordered steps |
| `update_workflow` | Save edits against an expected revision |
| `preview_workflow` | Evaluate an input without writing history or triggering actions |
| `run_workflow` | Execute a workflow with an optional idempotent event ID |
| `list_runs` | Read the latest 50 run outputs and step traces |
| `list_records` | Read the latest 100 saved records |
| `list_deliveries` | Read the latest 100 outbound delivery states |

## Receive an event

Save a workflow and open **Inbound webhook → Show connection details** in the editor. Supply the displayed workflow ID and key in your sender. For example, in a POSIX shell:

```sh
curl -X POST "http://127.0.0.1:8765/hooks/$WORKFLOW_ID" \
  -H "Content-Type: application/json" \
  -H "X-Flowdesk-Key: $WORKFLOW_KEY" \
  -H "Idempotency-Key: inquiry-001" \
  -d '{"name":"Alex","service":"website"}'
```

Retries with the same event ID and payload return the original run. Reusing the ID with different input returns HTTP 409. A processed event returns the run ID and workflow status. A filtered or failed workflow commits its run trace and creates zero records or deliveries.

## Send to another app

Add a **Send webhook** step and give it a destination alias, for example `crm`. Its body is the current JSON object. Start a worker from the same environment and OS user. Replace the example URL with the HTTPS webhook URL of your receiver.

```sh
export FLOWDESK_TARGETS='{"crm":"https://receiver.example/webhooks/intake"}'
flowdesk worker
```

On PowerShell, set `$env:FLOWDESK_TARGETS = '{"crm":"https://receiver.example/webhooks/intake"}'` and run `flowdesk worker`. Keep destination URLs with embedded credentials private. The worker sends each delivery with an `Idempotency-Key` header. Workflow completion queues the delivery. Its eventual HTTP outcome appears under **Deliveries**. A transport failure or an interrupted send is marked `unknown` after reconciliation. Check the receiver before manually resubmitting an event with a new ID.

## Operating scope

- MIT-licensed software with no subscription or per-run billing. Hosting and external services have their own terms and costs.
- Designed for one trusted local user. The editor listens on loopback. Local processes can read workflow data and webhook keys. For an external sender, forward only the specific `POST /hooks/<id>` endpoint through an HTTPS reverse proxy, forwarding the internal Host as `127.0.0.1`. Keep the editor and `/api` local.
- All three processes use `~/.flowdesk/workspace.sqlite3` by default. To share another location, give each process the same absolute `FLOWDESK_DB` path. Keep the database private and stop all three processes before copying its directory for a backup.
- Templates reference top-level JSON fields with `{{field}}`. Filters compare a field with a string using exact equality. A saved record captures the payload at that step. A workflow supports 24 ordered steps and 64 KiB input/output objects.
- This release focuses on workflow automation. The wider Pabbly suite, its native integration catalog, scheduling and OAuth account management are outside the implementation. [Public product review](docs/product-review.md)

## Tests

```sh
python -m unittest discover -s tests -v
```

The tests exercise the editor API, concurrent webhook retries, filter and failure behavior, outbound delivery with a mock HTTPS receiver, and a real MCP client/server exchange over stdio. For the desktop/mobile browser smoke test, install Playwright, run `python -m playwright install chromium`, then `python tests/browser_smoke.py`.