Quickstart

toorow runs on your own stack — you bring your own accounts and credentials, and nothing is hardcoded to the maintainers’ project. This guide gets a local server (and, optionally, the full platform) running.

Prerequisites

Git
Python 3.12 and uv
Node.js 22+ and pnpm 9.x — corepack enable is the simplest route
Docker Desktop / Engine with Compose — only needed for the full local platform

1. Clone and install

git clone https://github.com/toorow/toorow.git
cd toorow
uv sync --all-packages --frozen
pnpm -C ui install --frozen-lockfile
pnpm -C ui build:tokens

2. Run the MCP server

The Python process reads environment variables directly — it does not load the root .env automatically. For a minimal local server the defaults are enough (auth, workers, scheduling and alerts are disabled unless explicitly enabled):

uv run --package toorow-server python -m core.main

Set an alternate port with PORT:

PORT=8000 uv run --package toorow-server python -m core.main

$env:PORT = "8000"
uv run --package toorow-server python -m core.main

The MCP endpoint is http://localhost:8000/mcp.

3. Admin console (optional)

The server mounts the built administration console when ui/admin/dist/ exists:

pnpm -C ui --filter @toorow/admin build

For local UI development with hot reload:

pnpm -C ui --filter @toorow/admin dev

4. Full local platform (Docker)

The full stack (Nango + both PostgreSQL databases) runs in Docker. Copy the local infrastructure template and replace every placeholder secret:

cp infra/nango/.env.example infra/nango/.env

Generate the required 256-bit Nango encryption key and set it as NANGO_ENCRYPTION_KEY in infra/nango/.env:

python -c "import base64,secrets; print(base64.b64encode(secrets.token_bytes(32)).decode())"

Start Nango and both databases:

docker compose --env-file infra/nango/.env -f infra/nango/docker-compose.yml up -d

Apply the application migrations in numeric order:

for migration in $(find infra/nango/migrations -name '*.sql' | sort -V); do
  docker compose --env-file infra/nango/.env -f infra/nango/docker-compose.yml exec -T platform-db \
    psql -U connector -d connector -v ON_ERROR_STOP=1 < "$migration"
done

Get-ChildItem infra/nango/migrations/*.sql | Sort-Object Name | ForEach-Object {
  Get-Content -Raw $_.FullName | docker compose --env-file infra/nango/.env -f infra/nango/docker-compose.yml exec -T platform-db psql -U connector -d connector -v ON_ERROR_STOP=1
}

Local host ports:

Service	Port
MCP server	8000
Nango UI/API	3003
Application PostgreSQL	5432
Nango PostgreSQL	5433

Never run docker compose down -v unless deleting all local platform and Nango data is intentional. See infra/nango/README.md for Google OAuth registration and integration testing.

5. Local data pipeline (no cloud needed)

The seeded DuckDB/dbt loop works without any cloud credentials:

uv run python server/modules/google-analytics/seeds/run_local_loop.py

Getting started

Technical guides

Prerequisites

1. Clone and install

2. Run the MCP server

3. Admin console (optional)

4. Full local platform (Docker)

5. Local data pipeline (no cloud needed)

Next steps

Add a connector

Deploy on your own stack

​Prerequisites

​1. Clone and install

​2. Run the MCP server

​3. Admin console (optional)

​4. Full local platform (Docker)

​5. Local data pipeline (no cloud needed)

​Next steps

Add a connector

Deploy on your own stack

Prerequisites

1. Clone and install

2. Run the MCP server

3. Admin console (optional)

4. Full local platform (Docker)

5. Local data pipeline (no cloud needed)

Next steps