Connect MotherDuck to Claude Code

Explore MotherDuck databases, shares, tables and columns, run DuckDB SQL, and read Guides and Flights. Add Toolspoke to Claude Code once and it can use 17 MotherDuck actions. Your MotherDuck credential stays in Toolspoke, and you choose which actions Claude Code may call.

Set it up in Claude Code

Three steps, the first one once for every toolkit you will ever add.

  1. Add Toolspoke to Claude Code

    Run it in your project, then /mcp to sign in

    claude mcp add --transport http toolspoke https://toolspoke.com/mcp

    The sign-in opens in your browser, and Toolspoke asks you to approve it.

  2. Install MotherDuck and connect it

    Add MotherDuck to a project in your Toolspoke workspace.

    Access token. You provide it once, when you install the connector. Toolspoke encrypts it at rest and decrypts it only for the length of a single call, and the gateway attaches it to the outbound request itself, so it is never part of the arguments an agent sends.

    Access token
    app.motherduck.com → Settings → Access Tokens → Create token. Choose a read scaling token if this tool should only read, it reaches read replicas that reject every write, so query_rw fails on the server. A regular access token is needed for query_rw and run_flight. The token acts as the user or service account that created it, and reaches every database that user can.
  3. Choose what Claude Code may do

    All 17 actions start on. Switch off any of the 2 actions that change something in MotherDuck, and Claude Code gets a refusal if it tries.

What you can ask Claude Code for

A few of the MotherDuck actions that only read, so they are safe to try first.

  • List every database this account can reach, including attached shares
  • List the shares shared with this account, attached or not
  • List the tables and views in a database, optionally in one schema
  • List a table's or view's columns with their types

What Claude Code can do in MotherDuck

15 actions read and 2 delete or permanently change something.

Reads

  • List databases

    List every database this account can reach, including attached shares. Call this first to confirm the token works and to find the database names the other tools take.

  • List shares

    List the shares shared with this account, attached or not.

  • List tables

    List the tables and views in a database, optionally in one schema.

  • List columns

    List a table's or view's columns with their types. Use it before writing a query against an unfamiliar table.

  • List views

    List the views in a database, optionally filtered by name or comment.

  • Search catalog

    Find databases, schemas, tables, columns or shares by name across the whole account. Use it when you know roughly what a table is called but not where it lives.

  • Query

    Run one read-only DuckDB SQL statement against a database and return the rows. Statements that change data or schema are refused; use query_rw for those. Include your own LIMIT.

  • Ask docs question

    Ask a question about DuckDB or MotherDuck and get an answer from their documentation.

  • Get query guide

    Read the organization's Guides overview, its topics and root-level Guides with the metric definitions and join conventions to follow. Call it before writing SQL against unfamiliar business data.

  • List guides

    Browse the organization's Guides. With no topic, lists the root level; with a topic, lists the Guides in it.

  • Get guide

    Read one Guide's full markdown and metadata.

  • List flights

    List Flights, scheduled Python jobs that run on MotherDuck, with their schedules.

  • Get flight

    Read one Flight's metadata, source code, requirements and config.

  • List flight runs

    List a Flight's runs with their status and timing.

  • Get flight run logs

    Read one Flight run's status, exit code and log output. Use it to find why a run failed.

Deletes or permanently changes

  • Query rw

    Run one DuckDB SQL statement that may change data or schema: INSERT, UPDATE, DELETE, CREATE, DROP, ATTACH. Destructive because DROP and DELETE remove data with no undo.

  • Run flight

    Start a run of a Flight now. Destructive because a Flight is arbitrary Python with the owner's credentials, so a run can write or delete data, and it bills compute.

MotherDuck in Claude Code: questions

Does Claude Code see my MotherDuck credential?

No. The credential is stored encrypted in Toolspoke, and the gateway adds it to each call. Claude Code only ever talks to Toolspoke, and the dashboard shows the last four characters of the credential and nothing more.

Can I stop Claude Code from changing things in MotherDuck?

Yes. Each of the 17 actions can be switched off for a project. Turn off the 2 that change something and Claude Code can only read.

Will 17 actions crowd Claude Code's context?

No. Toolspoke shows Claude Code five bridge tools, plus a guide where a toolkit has one, and Claude Code searches for the MotherDuck action it needs when it needs it. Adding more toolkits does not add more tools to its list.

Can I add it once for every project?

Yes. Add --scope user to the command and Claude Code keeps Toolspoke in every project on this machine. Without it, the server is added to the project you ran the command in.

What does it cost?

Tool calls are free on every plan, and a MotherDuck call does not run in a sandbox, so it bills nothing.

Try MotherDuck in Claude Code

Free to start, and tool calls cost nothing on any plan.