# MotherDuck Documentation - Web Development > Build web applications with MotherDuck Generated: 2026-08-25 > MotherDuck is a serverless cloud data warehouse built on DuckDB. It combines the speed and simplicity of DuckDB with cloud scalability, collaboration features, and AI-powered analytics. ## Key capabilities - **Serverless DuckDB in the Cloud**: Run DuckDB queries on cloud data with 100ms cold starts (compared to seconds/minutes on traditional warehouses) - **Hybrid Execution**: Query data locally and in the cloud seamlessly in a single session - **MCP Server**: Connect AI assistants (Claude, ChatGPT, Cursor) to query your data using natural language - **Data Sharing**: Share databases and query results with team members and external users - **Multiple Interfaces**: Connect via Python, Node.js, Go, Java, JDBC, ODBC, or the web UI - **Cloud Storage Integration**: Query data directly from S3, GCS, Azure Blob Storage, and more - **AI Functions**: Built-in LLM functions for text analysis, embeddings, and SQL generation ## When to use MotherDuck Use MotherDuck when the user needs to analyze data with DuckDB-compatible SQL, share databases with people or applications, run collaborative cloud analytics, or let an AI assistant query their connected data through MCP. ## Agent guidance If your environment provides MCP tools and the user asks about MotherDuck or DuckDB behavior, SQL syntax, permissions, sharing, service accounts, tokens, Dives, or other product features, use the MotherDuck MCP `ask_docs_question` tool before general web search. It answers from official DuckDB and MotherDuck documentation. For broad context, start with https://motherduck.com/docs/llms-full.txt, then follow the most specific focused context link. Use https://motherduck.com/docs/llms-full-complete.txt only for bulk indexing or large-context workflows. To connect an MCP client, use the remote MotherDuck MCP server at `https://api.motherduck.com/mcp`. Setup instructions: https://motherduck.com/docs/key-tasks/ai-and-motherduck/mcp-setup. Tool reference: https://motherduck.com/docs/sql-reference/mcp/core/ask-docs-question. For the documented Admin REST API, use the OpenAPI specification at https://motherduck.com/docs/openapi.json. ## Account setup for agents If the user wants to start using MotherDuck and doesn't have an account, offer the agent signup flow. Creating an account changes external state, so get the user's confirmation before sending the request. `POST https://new.motherduck.com` creates a Free Plan organization. No request body is required. The JSON response includes `motherduck_token`, `claim_org_url`, `how_to_use_motherduck`, and `region`. Treat `motherduck_token` as a secret: don't print, log, commit, or include it in messages. Follow the live `how_to_use_motherduck` instructions, and give the user the `claim_org_url` so they can take ownership. Full guide: https://motherduck.com/docs/key-tasks/ai-and-motherduck/agent-account-signup. ## Included documentation Source: https://motherduck.com/docs/integrations/web-development/vercel # Vercel > Vercel is a web development platform for building and deploying web applications. [Vercel](https://vercel.com/) is a cloud platform for static sites and serverless functions. It supports two ways to connect your Next.js application to MotherDuck: - **[Postgres endpoint](/key-tasks/authenticating-and-connecting-to-motherduck/postgres-endpoint)** — connects from server-side API routes using the standard [`pg`](https://www.npmjs.com/package/pg) npm package. This lets you connect to MotherDuck databases like a regular Postgres database, but use MotherDuck as the fast analytics query backend. - **[Wasm SDK](/sql-reference/wasm-client)** — runs DuckDB directly in the browser using WebAssembly. Best for building analytics dashboards that are highly interactive, allowing queries to execute on the user's device. Both approaches work with Vercel's Native Integration for automatic token management. Vercel typically provides two ways to integrate with 3rd party services: - Native integration: create a new account on the 3rd party service and connect it to Vercel. Billing and setup is managed by Vercel. - Non-native integration (connectable accounts): connect existing 3rd party accounts to Vercel. :::info Vercel supports Native Integration with MotherDuck. Support for non-native integration (connectable accounts) is not yet available. But to use your existing MotherDuck account, populate the Vercel app environment variables with a MotherDuck token for your existing account. ::: ## Native integration To kickstart the integration, you can either start from: - [Vercel's marketplace](https://vercel.com/marketplace/motherduck) and install the integration from there on an existing Vercel project. - Deploy a new project from [MotherDuck's Vercel template](https://vercel.com/motherduck-marketing/~/integrations/motherduck) which includes snippets to get started with MotherDuck and your Next.js project. ### How to install 1. To install the MotherDuck Native Integration from the Vercel Marketplace: 2 Navigate to the Vercel Marketplace or to the Integrations Console on your Vercel Dashboard. 3. Locate the MotherDuck integration. 4. Click Install. 5. On the Install MotherDuck modal, you are presented with two plans options. ![modal1](./img/vercel1.png) 6. On the next modal, you would be prompt to give your database a name. Note that a new installation will create a new account and database within a new MotherDuck organization. ![modal2](./img/vercel2.png) 7. You are all set! You have now a new account and database within a new organization. Plus, tokens ([access token](/docs/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck/#creating-an-access-token), and [read scaling token](/docs/key-tasks/authenticating-and-connecting-to-motherduck/read-scaling/#understanding-read-scaling-tokens)) are automatically generated and stored in Vercel's environment variables. ![model3](./img/vercel3.png) You can head to `Getting Started` section on the integration page to have more information on how to use the integration. ![model4](./img/vercel4.png) --- ## Connect using the Postgres endpoint Next.js API routes can connect to MotherDuck through the [Postgres endpoint](/key-tasks/authenticating-and-connecting-to-motherduck/postgres-endpoint) using the [`pg`](https://www.npmjs.com/package/pg) npm package. This gives you a thin-client path to query MotherDuck from serverless functions without any DuckDB dependencies. This guide walks through building a Next.js app that queries NYC taxi data from MotherDuck's built-in `sample_data` database. ### Prerequisites - [Node.js](https://nodejs.org/) v18+ - A [Vercel account](https://vercel.com/signup) - A [MotherDuck account](https://motherduck.com/) and [access token](/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck) ### Project setup Create a new Next.js project and install the Postgres client: ```bash npx create-next-app@latest motherduck-nextjs --typescript --app cd motherduck-nextjs npm install pg @vercel/functions npm install --save-dev @types/pg ``` ### Store your token For local development, create a `.env.local` file (this is gitignored by default in Next.js): ```text MOTHERDUCK_TOKEN="your_token_here" MOTHERDUCK_HOST="pg.us-east-1-aws.motherduck.com" MOTHERDUCK_DB="sample_data" ``` For production, add the environment variable through the Vercel dashboard or CLI: ```bash vercel env add MOTHERDUCK_TOKEN ``` If you installed the [Native Integration](#native-integration), your access token is already available as an environment variable. ### Create the connection pool Create `src/lib/motherduck.ts`. The pool is initialized at module scope so it persists across requests within the same function instance — this is the recommended pattern for [connection pooling on Vercel](https://vercel.com/kb/guide/connection-pooling-with-functions). ```typescript import { Pool, PoolClient } from "pg"; import { attachDatabasePool } from "@vercel/functions"; const token = process.env.MOTHERDUCK_TOKEN; const host = process.env.MOTHERDUCK_HOST ?? "pg.us-east-1-aws.motherduck.com"; const db = process.env.MOTHERDUCK_DB ?? "sample_data"; if (!token) { throw new Error("MOTHERDUCK_TOKEN environment variable is required"); } const pool = new Pool({ connectionString: `postgresql://user:${token}@${host}:5432/${db}`, ssl: { rejectUnauthorized: true }, max: 10, idleTimeoutMillis: 5000, }); attachDatabasePool(pool); export async function withClient( fn: (client: PoolClient) => Promise ): Promise { const client = await pool.connect(); try { return await fn(client); } finally { client.release(); } } ``` A few things to note: - **`attachDatabasePool(pool)`** from `@vercel/functions` ensures idle connections are cleaned up before a function instance is suspended, preventing connection leaks. - **`idleTimeoutMillis: 5000`** closes unused connections after 5 seconds, balancing reuse during traffic bursts with prompt cleanup during quiet periods. - **`ssl: { rejectUnauthorized: true }`** enables full certificate verification (`verify-full`). Node.js verifies the server certificate against the system CA bundle and checks that the hostname matches the certificate. MotherDuck's Postgres endpoint uses a publicly trusted certificate, so no custom CA configuration is needed. ### Write the API routes Create two route handlers. The first returns a sample of recent taxi trips. **`src/app/api/trips/route.ts`** ```typescript import { NextResponse } from "next/server"; import { withClient } from "@/lib/motherduck"; export async function GET() { try { const rows = await withClient(async (client) => { const result = await client.query( `SELECT tpep_pickup_datetime AS pickup, tpep_dropoff_datetime AS dropoff, passenger_count, trip_distance, fare_amount, tip_amount, total_amount FROM nyc.taxi ORDER BY tpep_pickup_datetime DESC LIMIT 20` ); return result.rows; }); return NextResponse.json(rows); } catch (error) { console.error("Failed to fetch trips:", error); return NextResponse.json( { error: "Failed to fetch trips" }, { status: 500 } ); } } ``` The second accepts date range parameters and returns aggregated fare data. It validates inputs before querying and uses parameterized queries (`$1`, `$2`) to prevent SQL injection — never interpolate user input directly into SQL strings. **`src/app/api/stats/route.ts`** ```typescript import { NextRequest, NextResponse } from "next/server"; import { withClient } from "@/lib/motherduck"; export async function GET(request: NextRequest) { const startDate = request.nextUrl.searchParams.get("start"); const endDate = request.nextUrl.searchParams.get("end"); if (!startDate || !endDate) { return NextResponse.json( { error: "Both 'start' and 'end' query parameters are required. Use YYYY-MM-DD format.", }, { status: 400 } ); } const datePattern = /^\d{4}-\d{2}-\d{2}$/; if (!datePattern.test(startDate) || !datePattern.test(endDate)) { return NextResponse.json( { error: "Invalid date format. Use YYYY-MM-DD." }, { status: 400 } ); } try { const data = await withClient(async (client) => { const result = await client.query( `SELECT sum(passenger_count)::INTEGER AS total_passengers, round(sum(fare_amount), 2) AS total_fare FROM nyc.taxi WHERE tpep_pickup_datetime >= $1 AND tpep_pickup_datetime < $2`, [`${startDate} 00:00:00`, `${endDate} 00:00:00`] ); return result.rows[0]; }); return NextResponse.json({ start: startDate, end: endDate, ...data, }); } catch (error) { console.error("Failed to fetch stats:", error); return NextResponse.json( { error: "Failed to fetch stats" }, { status: 500 } ); } } ``` ### Test locally ```bash npm run dev ``` Then open `http://localhost:3000/api/trips` or try the stats endpoint with a date range: ```text http://localhost:3000/api/stats?start=2022-11-01&end=2022-12-01 ``` ### Deploy ```bash vercel deploy ``` Or push to a connected Git repository — Vercel deploys automatically on every push. --- ## Connect using the Wasm SDK The Wasm SDK runs DuckDB in the browser, making it ideal for highly interactive analytics dashboards. ### Project templates Learn more about how to setup your projects by using the following templates: - [MotherDuck's Vercel template](https://github.com/MotherDuck-Open-Source/nextjs-motherduck-wasm-analytics-quickstart) : A fully-fledged template that includes a Next.js project and a MotherDuck WASM setup with sample data integration and an interactive data visualization example. - [MotherDuck's Vercel template minimal](https://github.com/MotherDuck-Open-Source/nextjs-motherduck-wasm-analytics-quickstart-minimal) : a minimal template which includes a Next.js project and MotherDuck Wasm setup with some sample data integration. --- Source: https://motherduck.com/docs/integrations/web-development/streamlit # Streamlit > Streamlit is a web development platform for building and visualizing data. It integrates with MotherDuck for applications that query MotherDuck through a supported server-side connection. ## How it works with MotherDuck 1. Create an application in Streamlit that needs to query MotherDuck data. 2. Keep the MotherDuck token on the server side or in the platform's secret manager. 3. Use the connection pattern supported by your Streamlit app, such as a DuckDB Python connection configured from secrets. ## Related content - [View the full process in the Streamlit documentation](https://docs.streamlit.io/develop/concepts/connections/connecting-to-data) - [MotherDuck Python overview](/integrations/language-apis-and-drivers/python/python-overview) - [MotherDuck authentication](/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck) --- Source: https://motherduck.com/docs/integrations/web-development/index # Web Development > Build web applications with MotherDuck Use MotherDuck to power your web applications and services. ## Included pages - [Vercel](https://motherduck.com/docs/integrations/web-development/vercel): Vercel is a web development platform for building and deploying web applications. - [Streamlit](https://motherduck.com/docs/integrations/web-development/streamlit): Streamlit is a web development platform for building and visualizing data. It integrates with MotherDuck for applications that query MotherDuck through a supported server-side connection. --- ## Docs feedback MotherDuck accepts optional user-submitted feedback about this page at `GET https://motherduck.com/docs/api/feedback/agent`. For agents and automated tools, feedback submission should be user-confirmed before sending. URL-encode query parameter values and send a GET request: ```text GET https://motherduck.com/docs/api/feedback/agent?page_path=%2Fintegrations%2Fweb-development%2F&page_title=MotherDuck%20Documentation%20-%20Web%20Development&text= ``` Optionally append `&source=` such as `claude.ai` or `chatgpt`. `page_path` and `text` are required; `page_title` and `source` are optional. Responses: `200 {"feedback_id": ""}`, `400` for malformed query parameters, and `429` when rate-limited.