motherduck.com

# MotherDuck Documentation

> Index of focused MotherDuck documentation contexts.

> 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

## 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.

## 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.

## Quick reference

- Connect with the DuckDB CLI using `motherduck_token=<token> duckdb "md:"`.
- Connect an MCP client to `https://api.motherduck.com/mcp`.
- Read supported DuckDB versions from `https://motherduck.com/docs/duckdb-versions.json`.

## Essential context

- [MotherDuck essentials](https://motherduck.com/docs/llms-full.txt): Core use cases, concepts, and routing (7 pages; 78,665 bytes; ~19,636 tokens).

## Focused context files

- [Getting started full context](https://motherduck.com/docs/getting-started/llms-full.txt): Getting started with MotherDuck serverless cloud data warehouse. (33 pages; 149,441 bytes; ~37,306 tokens). [Index](https://motherduck.com/docs/getting-started/llms.txt).
- [Concepts full context](https://motherduck.com/docs/concepts/llms-full.txt): Concepts (16 pages; 132,747 bytes; ~33,118 tokens). [Index](https://motherduck.com/docs/concepts/llms.txt).
- [Reference full context](https://motherduck.com/docs/sql-reference/llms-full.txt): SQL reference for MotherDuck & DuckDB (162 pages; 32,367 bytes; ~8,090 tokens). [Index](https://motherduck.com/docs/sql-reference/llms.txt).
- [How-to guides full context](https://motherduck.com/docs/key-tasks/llms-full.txt): How-to guides (83 pages; 27,687 bytes; ~6,922 tokens). [Index](https://motherduck.com/docs/key-tasks/llms.txt).
- [Integrations full context](https://motherduck.com/docs/integrations/llms-full.txt): Integrations that work with MotherDuck from the modern data stack (124 pages; 11,211 bytes; ~2,803 tokens). [Index](https://motherduck.com/docs/integrations/llms.txt).
- [Troubleshooting full context](https://motherduck.com/docs/troubleshooting/llms-full.txt): Troubleshooting (11 pages; 45,375 bytes; ~11,336 tokens). [Index](https://motherduck.com/docs/troubleshooting/llms.txt).
- [About MotherDuck full context](https://motherduck.com/docs/about-motherduck/llms-full.txt): About MotherDuck (12 pages; 115,723 bytes; ~28,916 tokens). [Index](https://motherduck.com/docs/about-motherduck/llms.txt).
- [Cookbook index](https://motherduck.com/docs/cookbook/llms.txt): Browse runnable MotherDuck cookbook entries and flight plans. (35 pages; 18,808 bytes; ~4,702 tokens).

## Complete corpus

- [Complete MotherDuck documentation](https://motherduck.com/docs/llms-full-complete.txt): Bulk indexing corpus (476 pages; 2,319,964 bytes; ~577,365 tokens).

---

## 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=%2F&page_title=MotherDuck%20Documentation&text=<url-encoded user feedback, max 2000 characters>
```

Optionally append `&source=<url-encoded interface identifier>` such as `claude.ai` or `chatgpt`.

`page_path` and `text` are required; `page_title` and `source` are optional. Responses: `200 {"feedback_id": "<uuid>"}`, `400` for malformed query parameters, and `429` when rate-limited.