> ## Documentation Index
> Fetch the complete documentation index at: https://docs.toorow.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Run the toorow MCP server and admin console on your own machine.

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](https://docs.astral.sh/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

```bash theme={null}
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):

```bash theme={null}
uv run --package toorow-server python -m core.main
```

Set an alternate port with `PORT`:

<CodeGroup>
  ```bash bash / zsh theme={null}
  PORT=8000 uv run --package toorow-server python -m core.main
  ```

  ```powershell PowerShell theme={null}
  $env:PORT = "8000"
  uv run --package toorow-server python -m core.main
  ```
</CodeGroup>

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

## 3. Admin console (optional)

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

```bash theme={null}
pnpm -C ui --filter @toorow/admin build
```

For local UI development with hot reload:

```bash theme={null}
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:

```bash theme={null}
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`:

```bash theme={null}
python -c "import base64,secrets; print(base64.b64encode(secrets.token_bytes(32)).decode())"
```

Start Nango and both databases:

```bash theme={null}
docker compose --env-file infra/nango/.env -f infra/nango/docker-compose.yml up -d
```

Apply the application migrations in numeric order:

<CodeGroup>
  ```bash bash / zsh theme={null}
  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
  ```

  ```powershell PowerShell theme={null}
  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
  }
  ```
</CodeGroup>

Local host ports:

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

<Warning>
  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.
</Warning>

## 5. Local data pipeline (no cloud needed)

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

```bash theme={null}
uv run python server/modules/google-analytics/seeds/run_local_loop.py
```

## Next steps

<CardGroup cols={2}>
  <Card title="Add a connector" icon="plug" href="/adding-a-connector">
    Extend toorow with your own ingestion module.
  </Card>

  <Card title="Deploy on your own stack" icon="cloud" href="/introduction">
    Provision BigQuery, Cloud Run and OAuth for a hosted instance.
  </Card>
</CardGroup>