MotherDuck MCP connector

1. Install the SDK

   Node.js

   npm install @scalekit-sdk/node

   Python

   pip install scalekit

   Full SDK reference: Node.js | Python

2. Set your credentials

   Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

   .env

   SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
   SCALEKIT_CLIENT_ID=<your-client-id>
   SCALEKIT_CLIENT_SECRET=<your-client-secret>

3. Authorize and make your first call

   Node.js

   quickstart.ts

   import { ScalekitClient } from '@scalekit-sdk/node'
   import 'dotenv/config'
   
   const scalekit = new ScalekitClient(
     process.env.SCALEKIT_ENV_URL,
     process.env.SCALEKIT_CLIENT_ID,
     process.env.SCALEKIT_CLIENT_SECRET,
   )
   const actions = scalekit.actions
   
   const connector = 'motherduckmcp'
   const identifier = 'user_123'
   
   // Generate an authorization link for the user
   const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
   console.log('Authorize MotherDuck MCP:', link)
   process.stdout.write('Press Enter after authorizing...')
   await new Promise(r => process.stdin.once('data', r))
   
   // Make your first call
   const result = await actions.executeTool({
     connector,
     identifier,
     toolName: 'motherduckmcp_get_flight_guide',
     toolInput: {},
   })
   console.log(result)

   Python

   quickstart.py

   import os
   from scalekit.client import ScalekitClient
   from dotenv import load_dotenv
   load_dotenv()
   
   scalekit_client = ScalekitClient(
       env_url=os.getenv("SCALEKIT_ENV_URL"),
       client_id=os.getenv("SCALEKIT_CLIENT_ID"),
       client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
   )
   actions = scalekit_client.actions
   
   connection_name = "motherduckmcp"
   identifier = "user_123"
   
   # Generate an authorization link for the user
   link_response = actions.get_authorization_link(
       connection_name=connection_name,
       identifier=identifier,
   )
   print("Authorize MotherDuck MCP:", link_response.link)
   input("Press Enter after authorizing...")
   
   # Make your first call
   result = actions.execute_tool(
       tool_input={},
       tool_name="motherduckmcp_get_flight_guide",
       connection_name=connection_name,
       identifier=identifier,
   )
   print(result)

What you can do

Connect this agent connector to let your agent:

• Dive view, save — Render a MotherDuck Dive as a live, interactive MCP app inside the host client
• Update flight, dive — Update a Flight’s source code, dependencies, config, authentication tokens, secrets, name, or schedule
• Data share dive — Make a Dive’s underlying data accessible to your organization by creating org-scoped shares for owned databases referenced by the Dive’s SQL queries
• Search catalog — Fuzzy search across the MotherDuck catalog (databases, schemas, tables, columns, shares) using Jaro-Winkler similarity scoring
• Run flight, cancel flight — Trigger an asynchronous execution of a Flight using its current version
• Read dive — Retrieve a Dive’s complete details including title, description, timestamps, and full React component source code

Tool list

Use the exact tool names from the Tool list below when you call execute_tool. If you’re not sure which name to use, list the tools available for the current user first.

motherduckmcp_ask_docs_question#Query official DuckDB and MotherDuck documentation to answer questions about SQL syntax, features, and best practices.1 param▾

Query official DuckDB and MotherDuck documentation to answer questions about SQL syntax, features, and best practices.

NameTypeRequiredDescription

questionstringrequiredQuestion about DuckDB or MotherDuck.

motherduckmcp_cancel_flight_run#Cancel an in-progress Flight run. Returns an error if the run is already in a terminal state.2 params▾

Cancel an in-progress Flight run. Returns an error if the run is already in a terminal state.

NameTypeRequiredDescription

idstringrequiredFlight identifier (UUID).

run_numberintegerrequiredSequential run number to cancel, as returned by list_flight_runs.

motherduckmcp_create_flight#Create a new Flight — a Python entrypoint with optional dependencies that executes on MotherDuck compute. Supports optional cron scheduling.7 params▾

Create a new Flight — a Python entrypoint with optional dependencies that executes on MotherDuck compute. Supports optional cron scheduling.

NameTypeRequiredDescription

namestringrequiredIdentifier for the Flight.

source_codestringrequiredPython program code for the Flight entrypoint. Should end with: if __name__ == "__main__": main()

configobjectoptionalNon-secret environment variable key-value pairs to pass to the Flight at runtime.

md_secret_namesarrayoptionalSecret names to surface as environment variables inside the Flight execution context.

md_token_namestringoptionalMotherDuck access token label; uses the default token if omitted.

requirements_txtstringoptionalPinned package dependencies in requirements.txt format, one package per line.

schedule_cronstringoptionalUTC 5-field cron expression for automatic scheduling (e.g. '0 9 * * 1' for Mondays at 9am UTC).

motherduckmcp_delete_dive#Permanently remove a Dive from the MotherDuck workspace. This action cannot be undone.1 param▾

Permanently remove a Dive from the MotherDuck workspace. This action cannot be undone.

NameTypeRequiredDescription

idstringrequiredUnique identifier of the Dive to delete.

motherduckmcp_delete_flight#Permanently delete a Flight, its versions, schedule, and run history. This action cannot be undone.1 param▾

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

NameTypeRequiredDescription

idstringrequiredFlight identifier (UUID) of the Flight to permanently delete.

motherduckmcp_dive_query#Execute a read-only DuckDB SQL query on behalf of a Dive, attributed to the specified Dive UUID. Used by the Dive viewer for query execution.3 params▾

Execute a read-only DuckDB SQL query on behalf of a Dive, attributed to the specified Dive UUID. Used by the Dive viewer for query execution.

NameTypeRequiredDescription

sqlstringrequiredRead-only DuckDB SQL query to execute.

databasestringoptionalDatabase name to query.

dive_idstringoptionalDive UUID for query attribution.

motherduckmcp_edit_dive_content#Edit a Dive's content by applying one or more text replacements and saving to MotherDuck. Reads current content, applies edits in sequence, validates, and persists. No prior read_dive call is needed.2 params▾

Edit a Dive's content by applying one or more text replacements and saving to MotherDuck. Reads current content, applies edits in sequence, validates, and persists. No prior read_dive call is needed.

NameTypeRequiredDescription

editsarrayrequiredList of edits to apply in sequence. Each edit specifies old_string, new_string, and optional replace_all flag.

idstringrequiredThe unique identifier (UUID) of the Dive to edit.

motherduckmcp_edit_flight_source#Edit a Flight's source code through one or more find-and-replace operations, producing a new FlightVersion. Applies edits sequentially and validates the result.2 params▾

Edit a Flight's source code through one or more find-and-replace operations, producing a new FlightVersion. Applies edits sequentially and validates the result.

NameTypeRequiredDescription

editsarrayrequiredList of find-and-replace edit operations to apply sequentially to the Flight source code.

idstringrequiredFlight identifier (UUID).

motherduckmcp_get_dive_guide#Retrieve comprehensive instructions for creating MotherDuck Dives (interactive React data apps), tailored to the calling AI client.1 param▾

Retrieve comprehensive instructions for creating MotherDuck Dives (interactive React data apps), tailored to the calling AI client.

NameTypeRequiredDescription

clientstringrequiredAI platform making the request.

motherduckmcp_get_flight#Fetch a Flight's metadata and version snapshot by UUID, including source code, requirements, config, secret names, and token name.2 params▾

Fetch a Flight's metadata and version snapshot by UUID, including source code, requirements, config, secret names, and token name.

NameTypeRequiredDescription

idstringrequiredFlight identifier.

versionintegeroptional1-indexed version number; omit for current version.

motherduckmcp_get_flight_guide#Retrieve the authoritative guide for working with MotherDuck Flights (anatomy, config vs. secrets, scheduling, run lifecycle, common failures). Call this first before using other Flight tools.0 params▾

Retrieve the authoritative guide for working with MotherDuck Flights (anatomy, config vs. secrets, scheduling, run lifecycle, common failures). Call this first before using other Flight tools.

motherduckmcp_get_flight_run_logs#Fetch the logs and run record for a single Flight run, combining stdout/stderr with status, exit code, and timing.3 params▾

Fetch the logs and run record for a single Flight run, combining stdout/stderr with status, exit code, and timing.

NameTypeRequiredDescription

idstringrequiredFlight identifier (UUID).

run_numberintegerrequiredSequential run number for this Flight, as returned by list_flight_runs.

max_bytesintegeroptionalCap response size in bytes (minimum 1024). When the log exceeds this limit, the tail of the log is returned.

motherduckmcp_get_short_lived_token#Returns a short-lived token and connection details for the MotherDuck database endpoint. Use this to obtain temporary credentials for direct database access.0 params▾

Returns a short-lived token and connection details for the MotherDuck database endpoint. Use this to obtain temporary credentials for direct database access.

motherduckmcp_list_columns#List all columns of a table or view with data types, nullability, and comments.3 params▾

List all columns of a table or view with data types, nullability, and comments.

NameTypeRequiredDescription

tablestringrequiredTable or view name. Accepts simple or fully qualified names (e.g. analytics.main.customers).

databasestringoptionalDatabase name; defaults to current database.

schemastringoptionalSchema name; defaults to current schema (main).

motherduckmcp_list_databases#Retrieve all databases accessible to the MotherDuck account, including owned databases and attached shared databases.0 params▾

Retrieve all databases accessible to the MotherDuck account, including owned databases and attached shared databases.

motherduckmcp_list_dives#Return all Dives owned in the MotherDuck workspace, including metadata like version history and timestamps. Optionally filter by keywords.1 param▾

Return all Dives owned in the MotherDuck workspace, including metadata like version history and timestamps. Optionally filter by keywords.

NameTypeRequiredDescription

keywordsstringoptionalKeywords to filter by title/description (case-insensitive, all words must match).

motherduckmcp_list_flight_runs#Retrieve the execution history of a Flight (newest first), including run number, status, timing, and effective config.2 params▾

Retrieve the execution history of a Flight (newest first), including run number, status, timing, and effective config.

NameTypeRequiredDescription

idstringrequiredFlight identifier (UUID).

limitintegeroptionalMaximum number of results to return (default 100, max 500).

motherduckmcp_list_flight_versions#Retrieve the complete version history of a Flight (newest first), enabling change tracking between versions.2 params▾

Retrieve the complete version history of a Flight (newest first), enabling change tracking between versions.

NameTypeRequiredDescription

idstringrequiredFlight identifier (UUID).

limitintegeroptionalMaximum number of results to return (default 100, max 500).

motherduckmcp_list_flights#List all Flights owned by the caller with summary metadata (UUID, name, schedule, status, current version). Optionally filter by keyword.2 params▾

List all Flights owned by the caller with summary metadata (UUID, name, schedule, status, current version). Optionally filter by keyword.

NameTypeRequiredDescription

keywordsstringoptionalFilter Flights by name (case-insensitive, all words must match).

limitintegeroptionalMaximum number of results to return (default 100, max 500).

motherduckmcp_list_shares#Retrieve all database shares that have been shared with the user by other MotherDuck users. Each share includes a name and URL for attaching via the ATTACH command.0 params▾

Retrieve all database shares that have been shared with the user by other MotherDuck users. Each share includes a name and URL for attaching via the ATTACH command.

motherduckmcp_list_tables#List all tables and views in a MotherDuck database, including schema, type (table or view), and any comments.2 params▾

List all tables and views in a MotherDuck database, including schema, type (table or view), and any comments.

NameTypeRequiredDescription

databasestringrequiredDatabase name to list tables from.

schemastringoptionalSchema filter; omitting returns tables from all schemas.

motherduckmcp_log_dive_viewer_event#Log a Dive viewer analytics event (e.g. render, query, mode change) to MotherDuck. Used by the Dive viewer for telemetry.12 params▾

Log a Dive viewer analytics event (e.g. render, query, mode change) to MotherDuck. Used by the Dive viewer for telemetry.

NameTypeRequiredDescription

event_namestringrequiredName of the analytics event to log.

app_namestringoptionalName of the MCP app logging the event.

app_versionstringoptionalVersion of the MCP app.

dive_idstringoptionalUUID of the Dive associated with this event.

duration_msnumberoptionalDuration of the operation in milliseconds.

error_messagestringoptionalError message if the operation failed.

from_modestringoptionalPrevious display mode before the transition.

row_countnumberoptionalNumber of rows returned by a query.

sql_previewstringoptionalTruncated SQL query text (first 200 chars) for logging.

stagestringoptionalProcessing stage for the event (e.g. compile, execute, database_validation).

successbooleanoptionalWhether the operation succeeded.

to_modestringoptionalNew display mode after the transition.

motherduckmcp_mint_dive_state_reference#Store a Dive UI state bag server-side and return its reference ID. Used when the inline-encoded state would exceed URL length limits. The returned ID is encoded into the Dive URL hash for retrieval on open.2 params▾

Store a Dive UI state bag server-side and return its reference ID. Used when the inline-encoded state would exceed URL length limits. The returned ID is encoded into the Dive URL hash for retrieval on open.

NameTypeRequiredDescription

dive_idstringrequiredUUID of the Dive the state bag belongs to.

stateobjectrequiredFull useDiveState snapshot to store. Each key matches a useDiveState(key) call inside the Dive. Must JSON-serialize to <= 64 KB.

motherduckmcp_query#Execute read-only SQL queries against MotherDuck databases using DuckDB SQL syntax. Cross-database queries are supported via fully qualified names. Results are capped at 2,048 rows and 50,000 characters. Timeout is 55 seconds.2 params▾

Execute read-only SQL queries against MotherDuck databases using DuckDB SQL syntax. Cross-database queries are supported via fully qualified names. Results are capped at 2,048 rows and 50,000 characters. Timeout is 55 seconds.

NameTypeRequiredDescription

databasestringrequiredDatabase name to query.

sqlstringrequiredDuckDB SQL statement (read-only; mutation statements are rejected).

motherduckmcp_query_rw#Execute SQL statements that can read or modify data and schema in MotherDuck databases using DuckDB SQL syntax. Supports DDL and DML operations. Results are capped at 2,048 rows and 50,000 characters. Timeout is 55 seconds.2 params▾

Execute SQL statements that can read or modify data and schema in MotherDuck databases using DuckDB SQL syntax. Supports DDL and DML operations. Results are capped at 2,048 rows and 50,000 characters. Timeout is 55 seconds.

NameTypeRequiredDescription

sqlstringrequiredDuckDB SQL statement (read or write).

databasestringoptionalDatabase name to target. Required when targeting database objects; optional for account-level operations.

motherduckmcp_read_dive#Retrieve a Dive's complete details including title, description, timestamps, and full React component source code.2 params▾

Retrieve a Dive's complete details including title, description, timestamps, and full React component source code.

NameTypeRequiredDescription

idstringrequiredUnique identifier of the Dive.

versionnumberoptionalVersion number to retrieve (1-indexed); defaults to latest.

motherduckmcp_run_flight#Trigger an asynchronous execution of a Flight using its current version. Returns a Run record immediately in PENDING or RUNNING state.2 params▾

Trigger an asynchronous execution of a Flight using its current version. Returns a Run record immediately in PENDING or RUNNING state.

NameTypeRequiredDescription

idstringrequiredFlight identifier (UUID) to trigger an execution for.

configobjectoptionalKey-value pairs to override stored config for this execution only. Does not persist to the Flight definition.

motherduckmcp_save_dive#Create a new Dive in the MotherDuck workspace. Validates JSX/React component code and analyzes database dependencies.3 params▾

Create a new Dive in the MotherDuck workspace. Validates JSX/React component code and analyzes database dependencies.

NameTypeRequiredDescription

contentstringrequiredJSX/React component code.

titlestringrequiredName of the Dive.

descriptionstringoptionalBrief explanation of the Dive.

motherduckmcp_search_catalog#Fuzzy search across the MotherDuck catalog (databases, schemas, tables, columns, shares) using Jaro-Winkler similarity scoring. Results are ranked by relevance.2 params▾

Fuzzy search across the MotherDuck catalog (databases, schemas, tables, columns, shares) using Jaro-Winkler similarity scoring. Results are ranked by relevance.

NameTypeRequiredDescription

querystringrequiredSearch term; supports partial matching, underscores, dots.

object_typesarrayoptionalFilter to specific object types. If omitted, searches all types.

motherduckmcp_share_dive_data#Make a Dive's underlying data accessible to your organization by creating org-scoped shares for owned databases referenced by the Dive's SQL queries.1 param▾

Make a Dive's underlying data accessible to your organization by creating org-scoped shares for owned databases referenced by the Dive's SQL queries.

NameTypeRequiredDescription

diveIdstringrequiredUnique identifier of the Dive.

motherduckmcp_update_dive#Update an existing Dive's title, description, or content. At least one optional field must be provided.4 params▾

Update an existing Dive's title, description, or content. At least one optional field must be provided.

NameTypeRequiredDescription

idstringrequiredUnique identifier of the Dive to update.

contentstringoptionalNew JSX/React component code.

descriptionstringoptionalNew description for the Dive.

titlestringoptionalNew title for the Dive.

motherduckmcp_update_flight#Update a Flight's source code, dependencies, config, authentication tokens, secrets, name, or schedule. Omitted fields remain unchanged. Code/dependency/config/secret changes create a new FlightVersion.8 params▾

Update a Flight's source code, dependencies, config, authentication tokens, secrets, name, or schedule. Omitted fields remain unchanged. Code/dependency/config/secret changes create a new FlightVersion.

NameTypeRequiredDescription

idstringrequiredFlight identifier (UUID).

configobjectoptionalFull replacement config map of non-secret environment variable key-value pairs. Providing this field creates a new FlightVersion.

md_secret_namesarrayoptionalReplacement list of secret names to surface as environment variables. Providing this field creates a new FlightVersion.

md_token_namestringoptionalMotherDuck token label for authentication. Providing this field creates a new FlightVersion.

namestringoptionalUpdated name for the Flight (metadata-only change, does not create a new FlightVersion).

requirements_txtstringoptionalPackage dependencies in requirements.txt format. Providing this field creates a new FlightVersion.

schedule_cronstringoptional5-field cron expression in UTC. Pass an empty string to clear the existing schedule.

source_codestringoptionalPython entrypoint code. Providing this field creates a new FlightVersion.

motherduckmcp_view_dive#Render a MotherDuck Dive as a live, interactive MCP app inside the host client.3 params▾

Render a MotherDuck Dive as a live, interactive MCP app inside the host client.

NameTypeRequiredDescription

dive_idstringrequiredUnique identifier of the Dive to render.

initial_stateobjectoptionalSeeds the Dive's UI state; keys match useDiveState hook calls; values must be JSON-serializable.

required_resourcesarrayoptionalOverride declared databases for this render. Each entry must have a url and an optional alias.