# MotherDuck Documentation - Client APIs > Client APIs for 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. ## Child contexts - [Python full context](https://motherduck.com/docs/getting-started/interfaces/client-apis/python/llms-full.txt): Connect and query MotherDuck from Python (5 pages; 14,645 bytes; ~3,659 tokens). [Index](https://motherduck.com/docs/getting-started/interfaces/client-apis/python/llms.txt). - [Other full context](https://motherduck.com/docs/getting-started/interfaces/client-apis/other/llms-full.txt): Other DuckDB client APIs that work with MotherDuck (5 pages; 8,681 bytes; ~2,171 tokens). [Index](https://motherduck.com/docs/getting-started/interfaces/client-apis/other/llms.txt). ## Included documentation Source: https://motherduck.com/docs/getting-started/interfaces/client-apis/index # Client APIs > Client APIs for MotherDuck MotherDuck works with all DuckDB client APIs. Choose your preferred language or driver below. ## Included pages - [Python](https://motherduck.com/docs/getting-started/interfaces/client-apis/python): Connect and query MotherDuck from Python - [Other client APIs](https://motherduck.com/docs/getting-started/interfaces/client-apis/other): Other DuckDB client APIs that work with MotherDuck --- Source: https://motherduck.com/docs/getting-started/interfaces/client-apis/python/installation-authentication # Installation & authentication > How to install DuckDB and connect to MotherDuck ## Prerequisites MotherDuck Python supports the following operating systems: - Linux (x64, glibc v2.31+, equivalent to ubuntu v20.04+) - Mac OSX 11+ (M1/ARM or x64) - Python 3.4 or later Please let us know if your configuration is unsupported. ## Installing DuckDB :::note MotherDuck supports DuckDB client versions 1.4.1 through 1.5.5 in all regions. For the range each region supports, see [client version support](/about-motherduck/cloud-regions/#client-version-support). ::: Use the following `pip` command to install the supported version of DuckDB: 

{`pip install duckdb==${ duckdbVersionRanges["us-east-1"].max }`}

## Connect to MotherDuck

You can connect to and work with multiple local and MotherDuck-hosted DuckDB databases at the same time. The connection syntax varies depending on how you’re opening local DuckDB and MotherDuck.

### Authenticating to MotherDuck

You can authenticate to MotherDuck using either browser-based authentication or an access token. Here are examples of both methods:

#### Using browser-based authentication

```python
import duckdb

# connect to MotherDuck using 'md:' or 'motherduck:'
con = duckdb.connect('md:')
```

When you run this code:

1. A URL and a code will be displayed in your terminal.
2. Your default web browser will automatically open to the URL.
3. You'll see a confirmation request to approve the connection.
4. Once, approved, if you're not already logged in to MotherDuck, you'll be prompted to do so.
5. Finally, you can close the browser tab and return to your Python environment.

This method is convenient for interactive sessions and doesn't require managing access tokens.

#### Using an access token

For automated scripts or environments where browser-based auth isn't suitable, you can use an access token:

```python
import duckdb

# Initiate a MotherDuck connection using an access token
con = duckdb.connect('md:?motherduck_token=')
```

Replace `` with an actual token generated from the MotherDuck UI.

To learn more about creating and managing access tokens, as well as other authentication options, see our guide on [Authenticating to MotherDuck](/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck/authenticating-to-motherduck.md).

### Connecting to MotherDuck

Once you've authenticated, you can connect to MotherDuck and start working with your data. Let's look at a few common scenarios.

#### Connecting directly to MotherDuck

Here's how to connect to MotherDuck and run a simple query:

```python
import duckdb

# Connect to MotherDuck via browser-based authentication
con = duckdb.connect('md:my_db')

# Run a query to verify the connection
con.sql("SHOW DATABASES").show()
```

:::tip
When connecting to MotherDuck, you need to specify a database name (like `my_db` in the example). If you're a new user, a default database called `my_db` is automatically created when your account is first set up. You can query any table in your connected database by just using its name. To switch databases, use the `USE` command.
:::

#### Working with both MotherDuck and local databases

MotherDuck lets you work with both cloud and local databases simultaneously. Here's how:

````python
import duckdb

# Connect to MotherDuck first, specifying a database
con = duckdb.connect('md:my_db')

# Then attach local DuckDB databases
con.sql("ATTACH 'local_database1.duckdb'")
con.sql("ATTACH 'local_database2.duckdb'")

# List all connected databases
con.sql("SHOW DATABASES").show()
````

#### Adding MotherDuck to an existing local connection

If you're already working with a local DuckDB database, you can add a MotherDuck connection:

````python
import duckdb

# Start with a local DuckDB database
local_con = duckdb.connect('local_database.duckdb')

# Add a MotherDuck connection, specifying a database
local_con.sql("ATTACH 'md:my_db'")
````

This is another approach to give you the flexibility to work with both local and cloud data in the same session.

---

Source: https://motherduck.com/docs/getting-started/interfaces/client-apis/python/choose-database

# Specify MotherDuck database
> Specify MotherDuck database
When you connect to MotherDuck you can specify a database name or omit the database name and connect to the default database.

- If you use `md:` without a database name, you connect to a default MotherDuck database called `my_db`.
- If you use `md:`, you connect to the `` database.

After you establish the connection, either the default database or the one you specify becomes the current database.

You can run the `USE` command to switch the current database, as shown in the following example.

```python
#list the current database
con.sql("SELECT current_database()").show()
# ('database1')

#switch the current database to database2
con.sql("USE database2")
```

To query a table in the current database, you can specify just the table name. To query a table in a different database, you can include the database name when you specify the table. You don't need to switch the current database. The following examples demonstrate each method.

```sql
#querying a table in the current database
con.sql("SELECT count(*) FROM mytable").show()

#querying a table in another database
con.sql("SELECT count(*) FROM another_db.another_table").show()
```

---

Source: https://motherduck.com/docs/getting-started/interfaces/client-apis/python/loading-data-into-md

# Loading data into MotherDuck with Python
> Load CSV, Parquet, and JSON files into MotherDuck from local, S3, or HTTPS sources using Python.
## Copying a table from a local DuckDB database into MotherDuck

You can use `CREATE TABLE AS SELECT` to load CSV, Parquet, and JSON files into MotherDuck from either local, Amazon S3, or https sources as shown in the following examples.

```python
# load from local machine into table mytable of the current/active used database
con.sql("CREATE TABLE mytable AS SELECT * FROM '~/filepath.csv'");
# load from an S3 bucket into table mytable of the current/active database
con.sql("CREATE TABLE mytable AS SELECT * FROM 's3://bucket/path/*.parquet'")
```

If the source data matches the table’s schema exactly you can also use `INSERT INTO ... SELECT` to append data, as shown in the following example.

```python
# append to table mytable in the currently selected database from S3
con.sql("INSERT INTO mytable SELECT * FROM ‘s3://bucket/path/*.parquet’")
```

:::tip
Use `INSERT INTO ... SELECT` to load data from files as shown above. Do not use single-row `INSERT INTO ... VALUES` statements in a loop — this is significantly slower because each statement incurs separate network overhead. See [Loading data best practices](/key-tasks/loading-data-into-motherduck/considerations-for-loading-data/) for more detail.
:::

## Copying an entire local DuckDB database to MotherDuck

MotherDuck supports copying your opened DuckDB database into a MotherDuck database. The following example copies a local DuckDB database named `localdb` into a MotherDuck-hosted database named `clouddb`.

```python
 # open the local db
local_con = duckdb.connect("localdb.ddb")
# connect to MotherDuck
local_con.sql("ATTACH 'md:'")
# The from indicates the file to upload. An empty path indicates the current database
local_con.sql("CREATE DATABASE clouddb FROM CURRENT_DATABASE()")
```

A local DuckDB database can also be copied by its file path:

```sql
local_con = duckdb.connect("md:")
local_con.sql("CREATE DATABASE clouddb FROM 'localdb.ddb'")
```

See [Loading Data into MotherDuck](/key-tasks/loading-data-into-motherduck/loading-data-into-motherduck.mdx) for more detail.

---

Source: https://motherduck.com/docs/getting-started/interfaces/client-apis/python/query-data

# Query data
> Execute SQL queries against MotherDuck using Python with hybrid local and cloud execution.
For more information about database manipulation, see [MotherDuck SQL reference](/docs/sql-reference/motherduck-sql-reference/).

MotherDuck uses DuckDB under the hood, so nearly all [DuckDB SQL](https://duckdb.org/docs/) works in MotherDuck without differences.

MotherDuck uses [Dual Execution](/concepts/architecture-and-capabilities/#dual-execution) to decide where each part of a query runs, including across more than one location at once. If your data lives on your laptop, MotherDuck runs the query against that data on your laptop. If you are joining data on your laptop to data on Amazon S3, MotherDuck runs each part of the query where the data lives before bringing the results together locally.

## Querying data in MotherDuck

You can query data loaded into MotherDuck the same way you query data in your DuckDB databases. MotherDuck executes these queries using resources in the cloud.

```sql
# table table_name is in MotherDuck storage
con.sql("SELECT * FROM table_name").show();
```

## Querying data on your machine

You can use MotherDuck to query files on your local machine. These queries execute using your machine's resources.

```sql
# query a Parquet file on your local machine
con.sql("SELECT * FROM '~/file.parquet'").show();

# query a table in a local DuckDB database
con.sql("SELECT * FROM local_table").show();
```

## Joining data across multiple locations

You can use MotherDuck to join data:

- In MotherDuck
- On S3 or other cloud object stores (Azure, GCS, R2, etc)
- On your local machine

## What's next ?
Ready to share your DuckDB data with your colleagues? Read up on [Sharing In MotherDuck](/key-tasks/sharing-data/sharing-data.mdx).

---

Source: https://motherduck.com/docs/getting-started/interfaces/client-apis/python/index

# Python


> Connect and query MotherDuck from Python

Learn how to connect to MotherDuck and query your data using Python.

## Included pages

- [DuckDB Python installation and authentication](https://motherduck.com/docs/getting-started/interfaces/client-apis/python/installation-authentication): How to install DuckDB and connect to MotherDuck
- [Specify MotherDuck database](https://motherduck.com/docs/getting-started/interfaces/client-apis/python/choose-database): Specify MotherDuck database
- [Loading data into MotherDuck with Python](https://motherduck.com/docs/getting-started/interfaces/client-apis/python/loading-data-into-md): Load CSV, Parquet, and JSON files into MotherDuck from local, S3, or HTTPS sources using Python.
- [Query data](https://motherduck.com/docs/getting-started/interfaces/client-apis/python/query-data): Execute SQL queries against MotherDuck using Python with hybrid local and cloud execution.

---

Source: https://motherduck.com/docs/getting-started/interfaces/client-apis/other/c

# C
> MotherDuck + C
The MotherDuck integration with C is no different than DuckDB. For more information, see [C](https://duckdb.org/docs/stable/clients/c/overview.html) in DuckDB Documentation.

---

Source: https://motherduck.com/docs/getting-started/interfaces/client-apis/other/odbc

# ODBC
> Connect to MotherDuck with the DuckDB ODBC driver, and authenticate a DSN with an access token instead of a browser sign-in.
The MotherDuck integration with ODBC is no different than DuckDB. For more information, see [ODBC](https://duckdb.org/docs/stable/clients/odbc/overview.html) in DuckDB Documentation.

To reach MotherDuck, set the **Database** field of your DSN to a MotherDuck database with the `md:` prefix:

```text
md:my_database
```

## Authenticating with an access token

With no token configured, the driver opens a browser sign-in prompt, and every application that uses the DSN prompts again each session. To authenticate the DSN itself, append your [access token](/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck/#creating-an-access-token) to the **Database** field as a connection string parameter:

```text
md:my_database?motherduck_token=
```

This works for any application that reads the DSN, including tools that don't expose a separate field for driver connection properties.

Add any other [connection string parameter](/sql-reference/connection-string-parameters) the same way, separated by `&`. BI tools often benefit from `attach_mode=single`, because their catalog browsers can be confused by multiple attached databases:

```text
md:my_database?motherduck_token=&attach_mode=single
```

To serve several people from one DSN, create the token on a service account and give it a [read scaling](/key-tasks/authenticating-and-connecting-to-motherduck/read-scaling/read-scaling.mdx) pool size that matches your expected number of concurrent users.

### Windows DSN fields truncate long tokens

:::warning
**The ODBC Data Source Administrator shortens the Database field.** The text box holds around 255 characters and saves a truncated value without reporting an error. A truncated token fails to authenticate, so the connection falls back to the browser prompt.
:::

Write the full value into the registry instead:

1. Open Registry Editor by running `regedit`.
2. Navigate to the key for your DSN:
   - System DSN: `HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBC.INI\`
   - 32-bit System DSN: `HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\ODBC\ODBC.INI\`
   - User DSN: `HKEY_CURRENT_USER\SOFTWARE\ODBC\ODBC.INI\`
3. Double-click `Database`, paste the full `md:my_database?motherduck_token=` value, and click OK.

Restart the application that uses the DSN to pick up the change.

---

Source: https://motherduck.com/docs/getting-started/interfaces/client-apis/other/rust

# Rust
> MotherDuck + Rust
The MotherDuck integration with Rust is no different than DuckDB. For more information, see [Rust](https://duckdb.org/docs/stable/clients/rust.html) in DuckDB Documentation.

---

Source: https://motherduck.com/docs/getting-started/interfaces/client-apis/other/wasm

# WebAssembly (Wasm)
> MotherDuck + WebAssembly
The MotherDuck offers its own fork of DuckDB Wasm, which is [documented here](/sql-reference/wasm-client/).

For more information about DuckDB Wasm, see [WebAssembly](https://duckdb.org/docs/stable/clients/wasm/overview.html) in DuckDB Documentation.

---

Source: https://motherduck.com/docs/getting-started/interfaces/client-apis/other/index

# Other client APIs


> Other DuckDB client APIs that work with MotherDuck

MotherDuck has dedicated guides for several DuckDB client APIs:

- [Go driver](/integrations/language-apis-and-drivers/go-driver/)
- [JDBC driver](/integrations/language-apis-and-drivers/jdbc-driver/)
- [Node.js](/integrations/language-apis-and-drivers/node-js/)
- [R](/integrations/language-apis-and-drivers/r/)

For other DuckDB client APIs, use the pages below. For the complete list of client APIs, see the [DuckDB documentation](https://duckdb.org/docs/stable/clients/overview.html).

## Included pages

- [C](https://motherduck.com/docs/getting-started/interfaces/client-apis/other/c): MotherDuck + C
- [ODBC](https://motherduck.com/docs/getting-started/interfaces/client-apis/other/odbc): Connect to MotherDuck with the DuckDB ODBC driver, and authenticate a DSN with an access token instead of a browser sign-in.
- [Rust](https://motherduck.com/docs/getting-started/interfaces/client-apis/other/rust): MotherDuck + Rust
- [WebAssembly (Wasm)](https://motherduck.com/docs/getting-started/interfaces/client-apis/other/wasm): MotherDuck + WebAssembly

---

## 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=%2Fgetting-started%2Finterfaces%2Fclient-apis%2F&page_title=MotherDuck%20Documentation%20-%20Client%20APIs&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.