---
canonical_url: "https://docs.composio.dev/toolkits/motherduck_mcp"
markdown_url: "https://docs.composio.dev/toolkits/motherduck_mcp.md"
product: "platform"
version: null
last_updated: null
---

# MotherDuck MCP

Explore MotherDuck database schemas, query data, and manage Dives, Flights, and Guides through MotherDuck’s official hosted MCP server. Includes SQL writes, scheduled Python jobs, sharing, and deletion tools.

- **Category:** model context protocol
- **Auth:** DCR_OAUTH
- **Composio-managed OAuth available?** No
- **Tools:** 45
- **Triggers:** 0
- **Slug:** `MOTHERDUCK_MCP`
- **Version:** 00000000_00

## Tools

### Ask docs question

**Slug:** `MOTHERDUCK_MCP_ASK_DOCS_QUESTION`

Ask a question about DuckDB or MotherDuck. Returns answers from official documentation.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `question` | string | Yes | Question about DuckDB or MotherDuck |

### Cancel flight run

**Slug:** `MOTHERDUCK_MCP_CANCEL_FLIGHT_RUN`

Cancel an in-flight run of a flight. Identified by the flight UUID and the sequential run number (from list_flight_runs). Returns `canceled: true` on a successful transition; calling on an already-terminal run or one that doesn't exist returns a tool error.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | The flight UUID |
| `run_number` | integer | Yes | Sequential run number to cancel |

### Create flight

**Slug:** `MOTHERDUCK_MCP_CREATE_FLIGHT`

Create a new MotherDuck flight. Read the flight guide before you create your first flight. A flight is a Python entrypoint (`source_code`) plus an optional `requirements_txt` that runs on MotherDuck compute. Optionally provide an `access_token_name` so the flight can connect to MotherDuck at runtime; omit it to use the default MotherDuck Flights access token. Optionally provide a 5-field cron expression to run on a schedule, an optional `max_runtime_sec` to cap how long a run may take, and an optional `instance_type` (F4, F16 or F32) to pick the runner size. Use flights for ELT/ETL pipelines, loading external data into MotherDuck, refreshing materialized views, or any recurring Python job that reads/writes MotherDuck data.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Flight name (used in UI and logs) |
| `config` | object | No | Optional non-secret key/value pairs made available as env vars |
| `source_code` | string | Yes | Python source for the flight entrypoint (a single-file script with a top-level `def main(): ...`) |
| `instance_type` | string ("F4" | "F16" | "F32") | No | Optional runner size, named after its memory in GB: F4, F16 or F32. Omit to use your plan's default. Sizes above your plan's cap are rejected. |
| `schedule_cron` | string | No | Optional 5-field cron expression (UTC). Omit to create an on-demand-only flight. |
| `max_runtime_sec` | integer | No | Optional per-run timeout in seconds; 0 means no timeout. Omit to use your plan's default. Requests above your plan's cap are rejected. |
| `requirements_txt` | string | No | Optional `requirements.txt` contents for pip install (one pinned package per line). |
| `access_token_name` | string | No | Optional name of a MotherDuck access token label to use at runtime. Omit to use the default MotherDuck Flights access token. Run `SELECT * FROM md_access_tokens()` to list available labels. |
| `flight_secret_names` | array | No | Optional list of MotherDuck secret names made available as env vars |

### Create guide

**Slug:** `MOTHERDUCK_MCP_CREATE_GUIDE`

Create a new guide — a markdown document that agents read to answer this org's data questions correctly (metric definitions, join/filter conventions, pitfalls). Group related guides with a lowercase kebab-case `topic` (e.g. 'revenue-billing' or 'core/metrics'); omit it for a guide without a topic. Visibility is controlled by `access`: 'user' (private, default) or 'organization' (org-wide, permission-gated). Personal dive/flight style guides belong under topic 'dives' / 'flights' with access 'user'. Attach `references` to the 1–5 objects the guide is authoritative about.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `title` | string | Yes | Human-readable title. |
| `topic` | string | No | Slash-separated grouping label, e.g. 'revenue-billing' or 'core/metrics' (no leading/trailing slash). Omit for no topic. |
| `access` | string ("user" | "organization") | No | 'user' (private, default) or 'organization' (org-wide, permission-gated). |
| `content` | string | Yes | The full markdown body. |
| `references` | array | No | Structured references to the objects this guide explains. |
| `description` | string | No | Short one-line summary shown in the index. |
| `external_id` | string | No | Optional caller-provided id for this version (e.g. a git SHA). |
| `change_comment` | string | No | Optional note describing this initial version. |

### Delete dive

**Slug:** `MOTHERDUCK_MCP_DELETE_DIVE`

Delete a dive by ID. This action is permanent and cannot be undone.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | The unique identifier of the dive to delete |

### Delete flight

**Slug:** `MOTHERDUCK_MCP_DELETE_FLIGHT`

Permanently delete a flight, its versions, schedule, and run history. This action cannot be undone.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | The flight UUID |

### Delete guide

**Slug:** `MOTHERDUCK_MCP_DELETE_GUIDE`

Soft-delete a guide while preserving its version history. Identify it by `uuid`.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `uuid` | string | Yes | The guide's UUID, as returned by list_guides or a previous mutation. |

### Dive query

**Slug:** `MOTHERDUCK_MCP_DIVE_QUERY`

Execute a read-only DuckDB query on behalf of a dive. This tool is used by the dive viewer and is not intended for direct use by the AI assistant.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `sql` | string | Yes | SQL query to execute |
| `dive_id` | string | No | Dive UUID for fallback query attribution |
| `database` | string | No | Database name to query |

### Edit dive content

**Slug:** `MOTHERDUCK_MCP_EDIT_DIVE_CONTENT`

Edit a dive's content by applying one or more text replacements, then save to MotherDuck. Accepts `id` (dive UUID) and `edits` (an array of {old_string, new_string, replace_all?} objects). Reads the current content from MotherDuck, applies edits in sequence, validates, and persists. Example: {id: '...', edits: [{old_string: 'foo', new_string: 'bar'}]}. old_string must be unique unless replace_all is true. No prior read_dive call is needed.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | The unique identifier (UUID) of the dive to edit |
| `edits` | array | Yes | List of edits to apply in sequence. Each edit has old_string, new_string, and optional replace_all. |

### Edit flight source

**Slug:** `MOTHERDUCK_MCP_EDIT_FLIGHT_SOURCE`

Edit a flight's source_code by applying one or more text replacements, then save as a new FlightVersion. Accepts `id` (flight UUID) and `edits` (an array of {old_string, new_string, replace_all?} objects). Reads the current source_code, applies edits in sequence, validates, and persists. Example: {id: '...', edits: [{old_string: 'foo', new_string: 'bar'}]}. old_string must be unique unless replace_all is true. No prior get_flight call is needed.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | The flight UUID |
| `edits` | array | Yes | List of edits to apply in sequence. Each edit has old_string, new_string, and optional replace_all. |

### Edit guide content

**Slug:** `MOTHERDUCK_MCP_EDIT_GUIDE_CONTENT`

Edit a guide's markdown body by applying one or more text replacements, then save as a new version. Identify the guide by `uuid`. Reads the stored guide, applies edits in sequence, and persists. Example: {uuid: '<guide uuid>', edits: [{old_string: 'foo', new_string: 'bar'}]}. old_string must be unique unless replace_all is true. No prior get_guide call is needed.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `uuid` | string | Yes | The guide's UUID, as returned by list_guides or a previous mutation. |
| `edits` | array | Yes | List of edits to apply in sequence. Each edit has old_string, new_string, and optional replace_all. |
| `external_id` | string | No | Optional caller-provided id for this version (e.g. a git SHA). |
| `change_comment` | string | No | Optional note describing this version's change. |

### Get dive guide

**Slug:** `MOTHERDUCK_MCP_GET_DIVE_GUIDE`

Load instructions for creating MotherDuck dives. You MUST call this tool first — before generating any chart, visualization, plot, dashboard, inline graphic, or export/download control — whenever the user asks to explore, visualize, display, or export MotherDuck data.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `client` | string ("claude" | "chatgpt" | "claude_cowork" | "claude_code" | "other") | Yes | The client environment requesting the guide. Use 'claude' for Claude web/desktop Chat, 'chatgpt' for ChatGPT, 'claude_cowork' for Claude Cowork, 'claude_code' for Cursor/IDE integrations with local filesystem access, or 'other' for other MCP clients. |

### Get flight

**Slug:** `MOTHERDUCK_MCP_GET_FLIGHT`

Fetch a flight by UUID. Returns metadata plus a version snapshot (source code, requirements, config, secret names, token name). Omit `version` to get the current version; pass a 1-indexed version number to inspect history.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | The flight UUID |
| `version` | integer | No | Optional 1-indexed version number. Omit to get the current version. |

### Get flight guide

**Slug:** `MOTHERDUCK_MCP_GET_FLIGHT_GUIDE`

Load instructions for authoring, scheduling, running, and troubleshooting MotherDuck flights. Call this tool first whenever the user asks about creating, updating, or operating a MotherDuck flight.

### Get flight logs

**Slug:** `MOTHERDUCK_MCP_GET_FLIGHT_LOGS`

Fetch the plain-text logs (stdout + stderr) of a flight run plus the matching `Run` record (status, exit_code, timing). Returns the last 200 lines by default; page with `limit`, `offset` and `order`. Pass `max_bytes` to cap the response size — the response is truncated to fit and the truncation is reported via `truncated: true`.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | The flight UUID |
| `limit` | integer | No | Max log lines to return (default: 200) |
| `order` | string ("asc" | "desc") | No | 'asc' reads from the first log line, 'desc' from the last (default: 'desc') |
| `offset` | integer | No | Number of lines to skip, counted from the end `order` reads from |
| `max_bytes` | integer | No | Optional max bytes of logs to return; the response is truncated to fit, keeping the end `order` reads from. |
| `run_number` | integer | Yes | Sequential run number |

### Get flight run

**Slug:** `MOTHERDUCK_MCP_GET_FLIGHT_RUN`

Fetch a single run of a flight by its sequential run number (from list_flight_runs). Returns the same shape as a list_flight_runs entry: status (PENDING/RUNNING/SUCCEEDED/FAILED/CANCELLED), timing metadata, and the effective `config` the run executed with. Use this to poll one run's status instead of re-listing.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | The flight UUID |
| `run_number` | integer | Yes | Sequential run number to fetch |

### Get guide

**Slug:** `MOTHERDUCK_MCP_GET_GUIDE`

Load a guide by uuid. Guides are curated markdown documents about this organization's data (metric definitions, conventions, pitfalls). Find a guide's uuid with `list_guides` or via `get_query_guide` (start there before writing SQL), `get_dive_guide`, or `get_flight_guide`.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `uuid` | string | Yes | The guide's UUID, as returned by list_guides or a previous mutation. |
| `version` | integer | No | Optional version number to read; defaults to the current version. |

### Get query guide

**Slug:** `MOTHERDUCK_MCP_GET_QUERY_GUIDE`

Call this before writing SQL to answer a data question. Returns this organization's query guidance: what guides exist (curated markdown documents about the data — metric definitions, join/filter conventions, pitfalls), how to navigate them, and an overview of the available guide topics.

### Get short lived token

**Slug:** `MOTHERDUCK_MCP_GET_SHORT_LIVED_TOKEN`

Returns a short-lived token and connection details for the MotherDuck database endpoint.

### List columns

**Slug:** `MOTHERDUCK_MCP_LIST_COLUMNS`

List all columns of a table or view with their types and comments.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Max results to return (default: 100) |
| `table` | string | Yes | Table or view name |
| `schema` | string | No | Schema name (optional, defaults to 'main') |
| `database` | string | Yes | Database name |

### List databases

**Slug:** `MOTHERDUCK_MCP_LIST_DATABASES`

List all databases in your MotherDuck account. Shows each database's alias, type, and its `url` — a fully qualified MotherDuck database name (e.g. `md:my_db`) or share URL (e.g. in guide references). Optionally filter by keywords.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Max results to return (default: 100) |
| `keywords` | string | No | Optional keywords to filter databases by name (case-insensitive, any word can match) |

### List dives

**Slug:** `MOTHERDUCK_MCP_LIST_DIVES`

List all dives in MotherDuck. Dives are interactive React data apps that query live data. Returns metadata including current_version and status. Each dive has a governance status: 'endorsed' (admin-approved org source of truth — prefer these), 'ready' (author-reviewed), 'draft' (work in progress; the default for new dives), or 'archived' (retired; excluded unless include_archived is true). Results are ordered endorsed, ready, draft, then archived, most recently updated first. Use read_dive with the optional version parameter to retrieve a specific historical version. Optionally filter by keywords.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Max results to return (default: 100) |
| `keywords` | string | No | Optional keywords to filter dives by title or description (case-insensitive, all words must match) |
| `include_archived` | boolean | No | Include archived Dives in the results. Defaults to false. Archived Dives remain readable via read_dive by id. |
| `include_org_shares` | boolean | No | Include Dives shared with your organization. Defaults to false. |

### List flight runs

**Slug:** `MOTHERDUCK_MCP_LIST_FLIGHT_RUNS`

List executions of a flight, newest first. Each run has a sequential number, status (PENDING/RUNNING/SUCCEEDED/FAILED/CANCELLED), timing metadata, and the effective `config` it ran with (the flight version's config merged with any per-run overrides).

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | The flight UUID |
| `limit` | integer | No | Max results (default: 50) |
| `offset` | integer | No | Number of runs to skip, for paging back through history |

### List flights

**Slug:** `MOTHERDUCK_MCP_LIST_FLIGHTS`

List MotherDuck flights. Org admins see every flight in their organization (with `owner_name` identifying whose is whose); everyone else sees only their own. Returns metadata for each flight including schedule and current version. Optionally filter by keywords matching the flight name.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Max results to return (default: 50) |
| `offset` | integer | No | Number of flights to skip, for paging through results |
| `keywords` | string | No | Optional keywords to filter by flight name (case-insensitive, all words must match). Filters within the page selected by limit/offset, not across every flight. |
| `owner_only` | boolean | No | Restrict the listing to flights you own. Only meaningful for org admins, who see the whole org's flights by default; ignored for everyone else. |

### List flight versions

**Slug:** `MOTHERDUCK_MCP_LIST_FLIGHT_VERSIONS`

List the immutable versions of a flight, newest first. Each update to source_code / requirements_txt / config / access_token_name / flight_secret_names produces a new version.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | The flight UUID |
| `limit` | integer | No | Max results (default: 50) |
| `offset` | integer | No | Number of versions to skip, for paging back through history |

### List guides

**Slug:** `MOTHERDUCK_MCP_LIST_GUIDES`

Browse this organization's curated guides — markdown documents that capture organization and personal context about the data in MotherDuck. Called with no arguments, lists the root level: guides without topics plus every topic (folder) with its guide count. Pass `topic` to open a folder — you get the guides stored at that topic and the nested topics below it. Read a guide in full with `get_guide(uuid)`.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `topic` | string | No | Open this folder, e.g. 'revenue-billing' or 'core/metrics' (no leading/trailing slash). Omit for the root level. |

### List macros

**Slug:** `MOTHERDUCK_MCP_LIST_MACROS`

List all macros (table and scalar macros) in a MotherDuck database, with their schema and parameters. Optionally filter by schema or keywords.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Max results to return (default: 100) |
| `schema` | string | No | Schema name (optional, defaults to all schemas) |
| `database` | string | Yes | Database name to list macros from |
| `keywords` | string | No | Optional keywords to filter macros by name (case-insensitive, any word can match) |

### List shares

**Slug:** `MOTHERDUCK_MCP_LIST_SHARES`

List all database shares that have been shared with you. Returns share names and URLs. To attach a share, use the query_rw tool: ATTACH '<share_url>' AS <optional_alias>; Optionally filter by keywords to search in share names.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Max results to return (default: 100) |
| `keywords` | string | No | Optional keywords to filter shares by name (case-insensitive, any word can match) |

### List tables

**Slug:** `MOTHERDUCK_MCP_LIST_TABLES`

List all tables and views in a MotherDuck database with comments. Optionally filter by keywords. Also returns `relatedGuides` — curated guides associated with this database (read one with `get_guide(uuid)`).

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Max results to return (default: 100) |
| `schema` | string | No | Schema name (optional, defaults to all schemas) |
| `database` | string | Yes | Database name to list tables from |
| `keywords` | string | No | Optional keywords to filter tables/views by name or comment (case-insensitive, any word can match) |

### List views

**Slug:** `MOTHERDUCK_MCP_LIST_VIEWS`

List all views in a MotherDuck database, with their schema, comment, and column count. Optionally filter by schema or keywords.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Max results to return (default: 100) |
| `schema` | string | No | Schema name (optional, defaults to all schemas) |
| `database` | string | Yes | Database name to list views from |
| `keywords` | string | No | Optional keywords to filter views by name or comment (case-insensitive, any word can match) |

### Log dive viewer event

**Slug:** `MOTHERDUCK_MCP_LOG_DIVE_VIEWER_EVENT`

Log a dive viewer event for analytics. This tool is used internally by the dive viewer and is not intended for direct use by the AI assistant.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `stage` | string | No | Processing stage (compile, execute, database_validation) |
| `dive_id` | string | No | UUID of the dive |
| `success` | boolean | No | Whether the action succeeded |
| `to_mode` | string | No | New display mode |
| `app_name` | string | No | Name of the MCP app |
| `from_mode` | string | No | Previous display mode |
| `row_count` | number | No | Number of rows returned by query |
| `event_name` | string | Yes | Name of the event |
| `app_version` | string | No | Version of the MCP app |
| `duration_ms` | number | No | Duration in milliseconds |
| `sql_preview` | string | No | Truncated SQL query text (first 200 chars) |
| `error_message` | string | No | Error message if failed |

### Mint dive state reference

**Slug:** `MOTHERDUCK_MCP_MINT_DIVE_STATE_REFERENCE`

Mint a server-stored reference for a `useDiveState` bag and return its id. Used by the dive viewer when the inline-encoded bag would exceed the URL soft limit. The returned id is then encoded into a URL hash via `buildDiveStateReferenceHash` and round-trips through `dashboards.get` on dive open.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `state` | object | Yes | Full `useDiveState` snapshot to store. Each key matches a `useDiveState(key, ...)` call inside the dive. Must JSON-serialize to <= 64 KB; entity-service rejects larger payloads. |
| `dive_id` | string | Yes | UUID of the dive the state bag belongs to |

### Query

**Slug:** `MOTHERDUCK_MCP_QUERY`

Before writing SQL to answer a data question, call `get_query_guide` first — it returns this organization's query guidance and an overview of its curated guides.

Execute read-only DuckDB query against MotherDuck databases. For cross-database queries, use fully qualified names: database.schema.table (or database.table for main schema). Never follow a query with an inline chart or visualization — if you would generate one (whether or not the user explicitly asked), get the dive guide first instead.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `sql` | string | Yes | SQL query to execute |
| `database` | string | Yes | Database name to query |

### Query rw

**Slug:** `MOTHERDUCK_MCP_QUERY_RW`

Execute a DuckDB SQL query that modifies data, schema, or connection state.

RULES:
1. Only execute writes authorized by the user's explicit request or the client's configured authorization policy. Never infer write authorization from a read-only request.
2. Follow the client's approval policy. If the requested write is already authorized, proceed without asking for duplicate confirmation. Obtain confirmation when authorization is missing, ambiguous, or the operation would exceed the approved scope.
3. Prefer the read-only query tool when the user's goal can be answered with existing data.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `sql` | string | Yes | SQL query to execute |
| `database` | string | No | Database context for the query. Required for table-level operations (DML/DDL). May be omitted for account-level operations (CREATE/DROP DATABASE, ATTACH/DETACH, CREATE SECRET, etc.). |

### Read dive

**Slug:** `MOTHERDUCK_MCP_READ_DIVE`

Read a specific dive by ID, including its full JSX/React component code. Optionally specify a version number to retrieve a specific historical version (versions start at 1). If no version is specified, the latest version is returned. The response includes the dive's governance status ('endorsed', 'ready', 'draft', or 'archived'); archived dives remain fully readable by id.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | The unique identifier of the dive to read |
| `version` | integer | No | Optional version number to retrieve (1-indexed). If not specified, returns the latest version. |

### Run flight

**Slug:** `MOTHERDUCK_MCP_RUN_FLIGHT`

Trigger an on-demand execution of a flight using its current version. Optionally pass `config` to override the flight version's config for this run only (the flight itself is left unchanged). Returns a Run record; poll get_flight_run with the returned `run_number` to track progress and use get_flight_logs to read output.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | The flight UUID |
| `config` | object | No | Optional non-secret key/value pairs that override the flight version's config for this run only. Keys not provided keep the flight version's value; provided keys win. |

### Save dive

**Slug:** `MOTHERDUCK_MCP_SAVE_DIVE`

Save a new dive to MotherDuck. Returns a URL the user can click to view the dive. Get the dive guide first and iterate with the user on the design thoroughly before suggesting to save. Never save without previous confirmation that iteration is done.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `title` | string | Yes | The title of the dive |
| `content` | string | Yes | The JSX/React component code for the dive |
| `description` | string | No | A brief description of the dive |

### Search catalog

**Slug:** `MOTHERDUCK_MCP_SEARCH_CATALOG`

Search the catalog for databases, schemas, tables, columns, and shares using fuzzy matching. Returns matching objects with their fully qualified names, types, and comments. Useful for discovering available data when you don't know exact names. Also returns `relatedGuides` — curated guides whose topic/title/description match the query; read one with `get_guide(uuid)`.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | Yes | Search term to find in object names (supports partial matching, underscores, dots) |
| `object_types` | array | No | Optional filter to limit results to specific object types |

### Set guide access

**Slug:** `MOTHERDUCK_MCP_SET_GUIDE_ACCESS`

Set a guide's visibility to 'user' (private to the owner) or 'organization' (visible to the whole org). Identify it by `uuid`. Org-wide scoping is permission-gated.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `uuid` | string | Yes | The guide's UUID, as returned by list_guides or a previous mutation. |
| `access` | string ("user" | "organization") | Yes | 'user' (private) or 'organization' (org-wide, permission-gated). |

### Share dive data

**Slug:** `MOTHERDUCK_MCP_SHARE_DIVE_DATA`

Share the data for a dive with your organization. Creates org-scoped shares for owned databases used in the dive, and updates the dive so others in the organization can view it.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `diveId` | string | Yes | The unique identifier (UUID) of the dive |

### Update dive

**Slug:** `MOTHERDUCK_MCP_UPDATE_DIVE`

Update an existing dive's title, description, or content. Returns a URL the user can click to view the updated dive. At least one field must be provided.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | The unique identifier (UUID) of the dive to update |
| `title` | string | No | New title for the dive |
| `content` | string | No | New JSX/React component code |
| `description` | string | No | New description for the dive |

### Update flight

**Slug:** `MOTHERDUCK_MCP_UPDATE_FLIGHT`

Update a flight. Any subset of name, source_code, requirements_txt, schedule_cron, config, access_token_name, flight_secret_names, max_runtime_sec, or instance_type may be provided. Updates to source_code/requirements_txt/config/flight_secret_names/access_token_name/max_runtime_sec/instance_type create a new FlightVersion; name and schedule_cron are metadata-only. Pass schedule_cron as `""` (empty string) to remove the schedule; omit it to leave it unchanged.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | The flight UUID |
| `name` | string | No | New flight name |
| `config` | object | No | Replacement config map (full replace) |
| `source_code` | string | No | New Python entrypoint source (single-file) |
| `instance_type` | string ("F4" | "F16" | "F32") | No | New runner size, named after its memory in GB: F4, F16 or F32. Omit to leave it unchanged. Sizes above your plan's cap are rejected. |
| `schedule_cron` | string | No | New cron expression (UTC, 5 fields). Empty string clears the schedule. |
| `max_runtime_sec` | integer | No | New per-run timeout in seconds; 0 means no timeout. Omit to leave it unchanged. Requests above your plan's cap are rejected. |
| `requirements_txt` | string | No | New requirements.txt contents |
| `access_token_name` | string | No | New MotherDuck access token label to use at runtime. Omit to leave the current token unchanged. |
| `flight_secret_names` | array | No | Replacement list of MotherDuck secret names (full replace) |

### Update guide

**Slug:** `MOTHERDUCK_MCP_UPDATE_GUIDE`

Append a new version to an existing guide, identified by `uuid`. Omit `content` to keep the current text and just change metadata such as references. A supplied `references` list replaces the existing one (pass [] to clear them, omit to carry them forward). For small in-place edits use `edit_guide_content`. Use `create_guide` to make a new guide, `update_guide_metadata` to retitle or re-topic.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `uuid` | string | Yes | The guide's UUID, as returned by list_guides or a previous mutation. |
| `content` | string | No | New full markdown body. Omit to carry the current version's content forward. |
| `references` | array | No | Replaces the guide's references. Pass [] to clear; omit to carry them forward. |
| `external_id` | string | No | Optional caller-provided id for this version (e.g. a git SHA). |
| `change_comment` | string | No | Optional note describing this version's change. |

### Update guide metadata

**Slug:** `MOTHERDUCK_MCP_UPDATE_GUIDE_METADATA`

Change a guide's title, description, or topic without appending a content version. Identify it by `uuid`. Pass an empty `description` to clear it; pass an empty `topic` to remove the topic.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `uuid` | string | Yes | The guide's UUID, as returned by list_guides or a previous mutation. |
| `title` | string | No | New title. |
| `topic` | string | No | New grouping label, e.g. 'revenue-billing' or 'core/metrics' (no leading/trailing slash). Pass an empty string to remove the topic. |
| `description` | string | No | New one-line summary. Pass an empty string to clear it. |

### View dive

**Slug:** `MOTHERDUCK_MCP_VIEW_DIVE`

Open and render a MotherDuck Dive as a live MCP app with interactive charts. Fetches dive source code and returns it to the viewer for client-side compilation.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `dive_id` | string | Yes | UUID of the dive to open |
| `initial_state` | object | No | Seed the dive's initial UI state for this preview. When supplied, each key is read by the corresponding `useDiveState` call inside the dive. Useful when the user describes a specific view ("show me this filtered to last quarter") — pass that selection as initial_state instead of re-saving the dive. State stays in memory for the preview session; interactive changes do not round-trip back to the MCP host. Example shape: { "region": "us-east-1", "filters": ["alpha"], "count": 5 }. Do not use for ephemeral UI state (input drafts, dialog open/close) — those use plain useState inside the dive and aren't part of the dive-state bag. |
| `required_resources` | array | No | Override the dive's declared required resources for this preview. When supplied, the dive viewer attaches this list in place of the dive's source-declared REQUIRED_DATABASES. Useful when the user wants to preview against a specific share or embed configuration ("render this against the customer's analytics database instead of mine"). Example shape: [{ "url": "md:customer_analytics", "alias": "analytics" }]. Do not use as a substitute for fixing the dive's source — if the dive should permanently target different databases, edit the source and update_dive instead. |