The MotherDuck MCP connector routes your AI agent's tool calls to MotherDuck's own MCP server through Scalekit. Each user signs in to MotherDuck once, and Scalekit stores and refreshes their tokens, so your agent never handles credentials. It comes with 44 tools.
- Tools
- 44
- What they doRead · write · destructive
- 24 · 17 · 324 read17 write3 destructive
- Users sign in with
- OAuth
- OAuth app
- Scalekit's or your own
Setup
Install the SDK
Terminal window npm install @scalekit-sdk/node dotenvTerminal window pip install scalekit-sdk-python python-dotenvSet your credentials
Add your Scalekit credentials to your
.envfile. 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>Create the MotherDuck MCP connection
In AgentKit > Connections, create a MotherDuck MCP connection. The name you give it is the
connection_nameyour code passes. See Configure connections.Scalekit credentials are available for MotherDuck MCP server, so you don't need to register an OAuth app.
Authorize a user and make your first call
quickstart.mts import { ScalekitClient } from '@scalekit-sdk/node'import 'dotenv/config'import { createInterface } from 'node:readline/promises'const scalekit = new ScalekitClient(process.env.SCALEKIT_ENVIRONMENT_URL,process.env.SCALEKIT_CLIENT_ID,process.env.SCALEKIT_CLIENT_SECRET,)const actions = scalekit.actionsconst connector = 'motherduckmcp'const identifier = 'user_123'// Generate an authorization link for the userconst { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })console.log('Authorize MotherDuck MCP:', link)const rl = createInterface({ input: process.stdin, output: process.stdout })await rl.question('Press Enter after authorizing...')rl.close()// Make your first callconst result = await actions.executeTool({connector,identifier,toolName: 'motherduckmcp_get_flight_guide',toolInput: {},})console.log(result)Terminal window npx tsx quickstart.mtsquickstart.py import osfrom scalekit import ScalekitClientfrom dotenv import load_dotenvload_dotenv()scalekit_client = ScalekitClient(env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),client_id=os.getenv("SCALEKIT_CLIENT_ID"),client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),)actions = scalekit_client.actionsconnection_name = "motherduckmcp"identifier = "user_123"# Generate an authorization link for the userlink_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 callresult = actions.execute_tool(tool_input={},tool_name="motherduckmcp_get_flight_guide",connection_name=connection_name,identifier=identifier,)print(result)Terminal window python quickstart.pyEach user signs in once. See Authorize a user for the full flow and statuses.
Tools
Pass the exact name toexecute_toolmotherduckmcp_ask_docs_questionQuery official DuckDB and MotherDuck documentation to answer questions about SQL syntax, features, and best practices.Read-onlyAsk Docs Question
Query official DuckDB and MotherDuck documentation to answer questions about SQL syntax, features, and best practices.
Inputs
questionstringrequired- Question about DuckDB or MotherDuck.
motherduckmcp_dive_queryExecute a read-only DuckDB SQL query on behalf of a Dive, attributed to the specified Dive UUID.Read-onlyDive 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.
Inputs
sqlstringrequired- Read-only DuckDB SQL query to execute.
databasestring- Database name to query.
dive_idstring- Dive UUID for query attribution.
motherduckmcp_get_dive_guideRetrieve comprehensive instructions for creating MotherDuck Dives (interactive React data apps), tailored to the calling AI client.Read-onlyGet Dive Guide
Retrieve comprehensive instructions for creating MotherDuck Dives (interactive React data apps), tailored to the calling AI client.
Inputs
clientstringrequired- AI platform making the request.one of
claudechatgptclaude_coworkclaude_codeother
motherduckmcp_get_flightFetch a Flight's metadata and version snapshot by UUID, including source code, requirements, config, secret names, and token name.Read-onlyGet Flight
Fetch a Flight's metadata and version snapshot by UUID, including source code, requirements, config, secret names, and token name.
Inputs
idstringrequired- Flight identifier.
versioninteger- 1-indexed version number; omit for current version.
motherduckmcp_get_flight_guideRetrieve the authoritative guide for working with MotherDuck Flights (anatomy, config vs.Read-onlyGet 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.
Inputs
This tool takes no inputs.
motherduckmcp_get_flight_logsFetch the plain-text logs (stdout + stderr) of a Flight run plus the matching Run record (status, exit_code, timing).Read-onlyGet Flight Run Logs
Fetch the plain-text logs (stdout + stderr) of a Flight run plus the matching Run record (status, exit_code, timing). Logs may be large; pass max_bytes to cap the response size — the response will be the tail when truncated.
Inputs
idstringrequired- Flight identifier (UUID).
run_numberintegerrequired- Sequential run number, as returned by list_flight_runs.
max_bytesinteger- Optional max bytes of logs to return; the response is truncated to fit and the truncation is reported via truncated: true.
motherduckmcp_get_guideLoad a guide by uuid.Read-onlyGet 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, get_dive_guide, or get_flight_guide.
Inputs
uuidstringrequired- The guide's UUID, as returned by list_guides or a previous mutation.
versioninteger- Version number to read; defaults to the current version.
motherduckmcp_get_query_guideCall this before writing SQL to answer a data question.Read-onlyGet 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), how to navigate them, and an overview of the available guide topics.
Inputs
This tool takes no inputs.
motherduckmcp_get_short_lived_tokenReturns a short-lived token and connection details for the MotherDuck database endpoint.Read-onlyGet 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.
Inputs
This tool takes no inputs.
motherduckmcp_list_columnsList all columns of a table or view with data types, nullability, and comments.Read-onlyList Columns
List all columns of a table or view with data types, nullability, and comments.
Inputs
tablestringrequired- Table or view name. Accepts simple or fully qualified names (e.g. analytics.main.customers).
databasestring- Database name; defaults to current database.
schemastring- Schema name; defaults to current schema (main).
motherduckmcp_list_databasesRetrieve all databases accessible to the MotherDuck account, including owned databases and attached shared databases.Read-onlyList Databases
Retrieve all databases accessible to the MotherDuck account, including owned databases and attached shared databases.
Inputs
This tool takes no inputs.
motherduckmcp_list_divesReturn all Dives owned in the MotherDuck workspace, including metadata like version history and timestamps.Read-onlyList Dives
Return all Dives owned in the MotherDuck workspace, including metadata like version history and timestamps. Optionally filter by keywords.
Inputs
keywordsstring- Keywords to filter by title/description (case-insensitive, all words must match).
motherduckmcp_list_flight_runsRetrieve the execution history of a Flight (newest first), including run number, status, timing, and effective config.Read-onlyList Flight Runs
Retrieve the execution history of a Flight (newest first), including run number, status, timing, and effective config.
Inputs
idstringrequired- Flight identifier (UUID).
limitinteger- Maximum number of results to return (default 100, max 500).
motherduckmcp_list_flight_versionsRetrieve the complete version history of a Flight (newest first), enabling change tracking between versions.Read-onlyList Flight Versions
Retrieve the complete version history of a Flight (newest first), enabling change tracking between versions.
Inputs
idstringrequired- Flight identifier (UUID).
limitinteger- Maximum number of results to return (default 100, max 500).
motherduckmcp_list_flightsList all Flights owned by the caller with summary metadata (UUID, name, schedule, status, current version).Read-onlyList Flights
List all Flights owned by the caller with summary metadata (UUID, name, schedule, status, current version). Optionally filter by keyword.
Inputs
keywordsstring- Filter Flights by name (case-insensitive, all words must match).
limitinteger- Maximum number of results to return (default 100, max 500).
motherduckmcp_list_guidesBrowse this organization's curated guides — markdown documents that capture organization and personal context about the data in MotherDuck.Read-onlyList 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. Read a guide in full with get_guide(uuid).
Inputs
topicstring- Open this folder, e.g. 'revenue-billing' or 'core/metrics' (no leading/trailing slash). Omit for the root level.
motherduckmcp_list_macrosList all macros (table and scalar macros) in a MotherDuck database, with their schema and parameters.Read-onlyList Macros
List all macros (table and scalar macros) in a MotherDuck database, with their schema and parameters. Optionally filter by schema or keywords.
Inputs
databasestringrequired- Database name to list macros from.
keywordsstring- Optional keywords to filter macros by name (case-insensitive, any word can match).
limitinteger- Max results to return (default: 100).
schemastring- Schema name (optional, defaults to all schemas).
motherduckmcp_list_tablesList all tables and views in a MotherDuck database, including schema, type (table or view), and any comments.Read-onlyList Tables
List all tables and views in a MotherDuck database, including schema, type (table or view), and any comments.
Inputs
databasestringrequired- Database name to list tables from.
schemastring- Schema filter; omitting returns tables from all schemas.
motherduckmcp_list_viewsList all views in a MotherDuck database, with their schema, comment, and column count.Read-onlyList Views
List all views in a MotherDuck database, with their schema, comment, and column count. Optionally filter by schema or keywords.
Inputs
databasestringrequired- Database name to list views from.
keywordsstring- Optional keywords to filter views by name or comment (case-insensitive, any word can match).
limitinteger- Max results to return (default: 100).
schemastring- Schema name (optional, defaults to all schemas).
motherduckmcp_queryExecute read-only SQL queries against MotherDuck databases using DuckDB SQL syntax.Read-onlyQuery
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.
Inputs
databasestringrequired- Database name to query.
sqlstringrequired- DuckDB SQL statement (read-only; mutation statements are rejected).
motherduckmcp_read_diveRetrieve a Dive's complete details including title, description, timestamps, and full React component source code.Read-onlyRead Dive
Retrieve a Dive's complete details including title, description, timestamps, and full React component source code.
Inputs
idstringrequired- Unique identifier of the Dive.
versionnumber- Version number to retrieve (1-indexed); defaults to latest.
motherduckmcp_search_catalogFuzzy search across the MotherDuck catalog (databases, schemas, tables, columns, shares) using Jaro-Winkler similarity scoring.Read-onlySearch Catalog
Fuzzy search across the MotherDuck catalog (databases, schemas, tables, columns, shares) using Jaro-Winkler similarity scoring. Results are ranked by relevance.
Inputs
querystringrequired- Search term; supports partial matching, underscores, dots.
object_typesarray- Filter to specific object types. If omitted, searches all types.
motherduckmcp_view_diveRender a MotherDuck Dive as a live, interactive MCP app inside the host client.Read-onlyView Dive
Render a MotherDuck Dive as a live, interactive MCP app inside the host client.
Inputs
dive_idstringrequired- Unique identifier of the Dive to render.
initial_stateobject- Seeds the Dive's UI state; keys match useDiveState hook calls; values must be JSON-serializable.
required_resourcesarray- Override declared databases for this render. Each entry must have a url and an optional alias.
motherduckmcp_cancel_flight_runCancel an in-progress Flight run.WriteCancel Flight Run
Cancel an in-progress Flight run. Returns an error if the run is already in a terminal state.
Inputs
idstringrequired- Flight identifier (UUID).
run_numberintegerrequired- Sequential run number to cancel, as returned by list_flight_runs.
motherduckmcp_create_flightCreate a new Flight — a Python entrypoint with optional dependencies that executes on MotherDuck compute.WriteCreate Flight
Create a new Flight — a Python entrypoint with optional dependencies that executes on MotherDuck compute. Supports optional cron scheduling.
Inputs
namestringrequired- Identifier for the Flight.
source_codestringrequired- Python program code for the Flight entrypoint. Should end with: if __name__ == "__main__": main()
configobject- Non-secret environment variable key-value pairs to pass to the Flight at runtime.
md_secret_namesarray- Secret names to surface as environment variables inside the Flight execution context.
md_token_namestring- MotherDuck access token label; uses the default token if omitted.
requirements_txtstring- Pinned package dependencies in requirements.txt format, one package per line.
schedule_cronstring- UTC 5-field cron expression for automatic scheduling (e.g. '0 9 * * 1' for Mondays at 9am UTC).
motherduckmcp_create_guideCreate a new guide — a markdown document that agents read to answer this org's data questions correctly (metric definitions, join/filter conventions, pitfalls).WriteCreate 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). Attach references to the 1-5 objects the guide is authoritative about.
Inputs
contentstringrequired- The full markdown body.
titlestringrequired- Human-readable title.
accessstring- 'user' (private, default) or 'organization' (org-wide, permission-gated).one of
userorganization change_commentstring- Optional note describing this initial version.
descriptionstring- Short one-line summary shown in the index.
external_idstring- Optional caller-provided id for this version (e.g. a git SHA).
referencesarray- Structured references to the objects this guide explains.
topicstring- Slash-separated grouping label, e.g. 'revenue-billing' or 'core/metrics' (no leading/trailing slash). Omit for no topic.
motherduckmcp_edit_dive_contentEdit a Dive's content by applying one or more text replacements and saving to MotherDuck.WriteEdit 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.
Inputs
editsarrayrequired- List of edits to apply in sequence. Each edit specifies old_string, new_string, and optional replace_all flag.
idstringrequired- The unique identifier (UUID) of the Dive to edit.
motherduckmcp_edit_flight_sourceEdit a Flight's source code through one or more find-and-replace operations, producing a new FlightVersion.WriteEdit 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.
Inputs
editsarrayrequired- List of find-and-replace edit operations to apply sequentially to the Flight source code.
idstringrequired- Flight identifier (UUID).
motherduckmcp_edit_guide_contentEdit a guide's markdown body by applying one or more text replacements, then save as a new version.WriteEdit 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. old_string must be unique unless replace_all is true. No prior get_guide call is needed.
Inputs
editsarrayrequired- List of edits to apply in sequence. Each edit has old_string, new_string, and optional replace_all.
uuidstringrequired- The guide's UUID, as returned by list_guides or a previous mutation.
change_commentstring- Optional note describing this version's change.
external_idstring- Optional caller-provided id for this version (e.g. a git SHA).
motherduckmcp_log_dive_viewer_eventLog a Dive viewer analytics event (e.g.WriteLog Dive Viewer Event
Log a Dive viewer analytics event (e.g. render, query, mode change) to MotherDuck. Used by the Dive viewer for telemetry.
Inputs
event_namestringrequired- Name of the analytics event to log.
app_namestring- Name of the MCP app logging the event.
app_versionstring- Version of the MCP app.
dive_idstring- UUID of the Dive associated with this event.
duration_msnumber- Duration of the operation in milliseconds.
error_messagestring- Error message if the operation failed.
from_modestring- Previous display mode before the transition.
row_countnumber- Number of rows returned by a query.
sql_previewstring- Truncated SQL query text (first 200 chars) for logging.
stagestring- Processing stage for the event (e.g. compile, execute, database_validation).
successboolean- Whether the operation succeeded.
to_modestring- New display mode after the transition.
motherduckmcp_mint_dive_state_referenceStore a Dive UI state bag server-side and return its reference ID.WriteMint 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.
Inputs
dive_idstringrequired- UUID of the Dive the state bag belongs to.
stateobjectrequired- Full useDiveState snapshot to store. Each key matches a useDiveState(key) call inside the Dive. Must JSON-serialize to <= 64 KB.
motherduckmcp_query_rwExecute SQL statements that can read or modify data and schema in MotherDuck databases using DuckDB SQL syntax.WriteQuery (Read-Write)
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.
Inputs
sqlstringrequired- DuckDB SQL statement (read or write).
databasestring- Database name to target. Required when targeting database objects; optional for account-level operations.
motherduckmcp_run_flightTrigger an asynchronous execution of a Flight using its current version.WriteRun Flight
Trigger an asynchronous execution of a Flight using its current version. Returns a Run record immediately in PENDING or RUNNING state.
Inputs
idstringrequired- Flight identifier (UUID) to trigger an execution for.
configobject- Key-value pairs to override stored config for this execution only. Does not persist to the Flight definition.
motherduckmcp_save_diveCreate a new Dive in the MotherDuck workspace.WriteSave Dive
Create a new Dive in the MotherDuck workspace. Validates JSX/React component code and analyzes database dependencies.
Inputs
contentstringrequired- JSX/React component code.
titlestringrequired- Name of the Dive.
descriptionstring- Brief explanation of the Dive.
motherduckmcp_set_guide_accessSet a guide's visibility to 'user' (private to the owner) or 'organization' (visible to the whole org).WriteSet 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.
- Idempotent
Inputs
accessstringrequired- 'user' (private) or 'organization' (org-wide, permission-gated).one of
userorganization uuidstringrequired- The guide's UUID, as returned by list_guides or a previous mutation.
motherduckmcp_update_diveUpdate an existing Dive's title, description, or content.WriteUpdate Dive
Update an existing Dive's title, description, or content. At least one optional field must be provided.
Inputs
idstringrequired- Unique identifier of the Dive to update.
contentstring- New JSX/React component code.
descriptionstring- New description for the Dive.
titlestring- New title for the Dive.
motherduckmcp_update_flightUpdate a Flight's source code, dependencies, config, authentication tokens, secrets, name, or schedule.WriteUpdate 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.
Inputs
idstringrequired- Flight identifier (UUID).
configobject- Full replacement config map of non-secret environment variable key-value pairs. Providing this field creates a new FlightVersion.
md_secret_namesarray- Replacement list of secret names to surface as environment variables. Providing this field creates a new FlightVersion.
md_token_namestring- MotherDuck token label for authentication. Providing this field creates a new FlightVersion.
namestring- Updated name for the Flight (metadata-only change, does not create a new FlightVersion).
requirements_txtstring- Package dependencies in requirements.txt format. Providing this field creates a new FlightVersion.
schedule_cronstring- 5-field cron expression in UTC. Pass an empty string to clear the existing schedule.
source_codestring- Python entrypoint code. Providing this field creates a new FlightVersion.
motherduckmcp_update_guideAppend a new version to an existing guide, identified by uuid.WriteUpdate 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.
Inputs
uuidstringrequired- The guide's UUID, as returned by list_guides or a previous mutation.
change_commentstring- Optional note describing this version's change.
contentstring- New full markdown body. Omit to carry the current version's content forward.
external_idstring- Optional caller-provided id for this version (e.g. a git SHA).
referencesarray- Replaces the guide's references. Pass [] to clear; omit to carry them forward.
motherduckmcp_update_guide_metadataChange a guide's title, description, or topic without appending a content version.WriteUpdate 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.
- Idempotent
Inputs
uuidstringrequired- The guide's UUID, as returned by list_guides or a previous mutation.
descriptionstring- New one-line summary. Pass an empty string to clear it.
titlestring- New title.
topicstring- New grouping label, e.g. 'revenue-billing' or 'core/metrics' (no leading/trailing slash). Pass an empty string to remove the topic.
motherduckmcp_delete_divePermanently remove a Dive from the MotherDuck workspace.DestructiveDelete Dive
Permanently remove a Dive from the MotherDuck workspace. This action cannot be undone.
Inputs
idstringrequired- Unique identifier of the Dive to delete.
motherduckmcp_delete_flightPermanently delete a Flight, its versions, schedule, and run history.DestructiveDelete Flight
Permanently delete a Flight, its versions, schedule, and run history. This action cannot be undone.
Inputs
idstringrequired- Flight identifier (UUID) of the Flight to permanently delete.
motherduckmcp_delete_guideSoft-delete a guide while preserving its version history.DestructiveDelete Guide
Soft-delete a guide while preserving its version history. Identify it by uuid.
Inputs
uuidstringrequired- The guide's UUID, as returned by list_guides or a previous mutation.
No tools match.
