This MotherDuck DuckDB MCP server provides SQL analytics capabilities for AI Assistants and IDEs by connecting to DuckDB and MotherDuck databases. With it, you can:
- Initialize Connections: Connect to local DuckDB (in-memory, file-backed, read-only) or cloud-based MotherDuck databases (using access tokens)
- Retrieve Databases: Access available databases after connection initialization
- Read Schemas: Get table schemas from specific databases
- Execute SQL Queries: Run analytics and data manipulation on connected databases
- Hybrid Execution: Query data combining local and cloud sources
- Cloud Storage Integration: Access data from Amazon S3 and other cloud storage
- Data Sharing: Create and share databases (via MotherDuck functionality)
- Serverless Analytics: Run analytics without configuring instances or clusters
MotherDuck's DuckDB MCP Server
An MCP server implementation that interacts with DuckDB and MotherDuck databases, providing SQL analytics capabilities to AI Assistants and IDEs.
Resources
- Close the Loop: Faster Data Pipelines with MCP, DuckDB & AI (Blogpost)
- Faster Data Pipelines development with MCP and DuckDB (YouTube)
Features
- Hybrid execution: query data from local DuckDB or/and cloud-based MotherDuck databases
- Cloud storage integration: access data stored in Amazon S3 or other cloud storage thanks to MotherDuck's integrations
- Data sharing: create and share databases
- SQL analytics: use DuckDB's SQL dialect to query any size of data directly from your AI Assistant or IDE
- Serverless architecture: run analytics without needing to configure instances or clusters
Components
Prompts
The server provides one prompt:
duckdb-motherduck-initial-prompt
: A prompt to initialize a connection to DuckDB or MotherDuck and start working with it
Tools
The server offers one tool:
query
: Execute a SQL query on the DuckDB or MotherDuck database- Inputs:
query
(string, required): The SQL query to execute
- Inputs:
All interactions with both DuckDB and MotherDuck are done through writing SQL queries.
Getting Started
General Prerequisites
uv
installed, you can install it usingpip install uv
orbrew install uv
If you plan to use the MCP with Claude Desktop or any other MCP comptabile client, the client need to be installed.
Prerequisites for DuckDB
- No prerequisites. The MCP server can create an in-memory database on-the-fly
- Or connect to an existing local DuckDB database file , or one stored on remote object storage (e.g., AWS S3).
Prerequisites for MotherDuck
- Sign up for a MotherDuck account
- Generate an access token via the MotherDuck UI
- Store the token securely for use in the configuration
Usage with Cursor
- Install Cursor from cursor.com/downloads if you haven't already
- Open Cursor:
- To set it up globally for the first time, go to Settings->MCP and click on "+ Add new global MCP server".
- This will open a
mcp.json
file to which you add the following configuration:
Usage with VS Code
- For the quickest installation, click one of the "Install with UV" buttons at the top of this README.
Manual Installation
Add the following JSON block to your User Settings (JSON) file in VS Code. You can do this by pressing Ctrl + Shift + P
and typing Preferences: Open User Settings (JSON)
.
Optionally, you can add it to a file called .vscode/mcp.json
in your workspace. This will allow you to share the configuration with others.
Usage with Claude Desktop
- Install Claude Desktop from claude.ai/download if you haven't already
- Open the Claude Desktop configuration file:
- To quickly access it or create it the first time, open the Claude Desktop app, select Settings, and click on the "Developer" tab, finally click on the "Edit Config" button.
- Add the following configuration to your
claude_desktop_config.json
:
Important Notes:
- Replace
YOUR_MOTHERDUCK_TOKEN_HERE
with your actual MotherDuck token - Replace
YOUR_HOME_FOLDER_PATH
with the path to your home directory (needed by DuckDB for file operations). For example, on macOS, it would be/Users/your_username
- The
HOME
environment variable is required for DuckDB to function properly.
Securing your MCP Server when querying MotherDuck
If the MCP server is exposed to third parties and should only have read access to data, we recommend using a read scaling token and running the MCP server in SaaS mode.
Read Scaling Tokens are special access tokens that enable scalable read operations by allowing up to 4 concurrent read replicas, improving performance for multiple end users while restricting write capabilities. Refer to the Read Scaling documentation to learn how to create a read-scaling token.
SaaS Mode in MotherDuck enhances security by restricting it's access to local files, databases, extensions, and configurations, making it ideal for third-party tools that require stricter environment protection. Learn more about it in the SaaS Mode documentation.
Secure Configuration
Connect to local DuckDB
To connect to a local DuckDB, instead of using the MotherDuck token, specify the path to your local DuckDB database file or use :memory:
for an in-memory database.
In-memory database:
Local DuckDB file:
Local DuckDB file in readonly mode:
Note: readonly mode for local file-backed DuckDB connections also makes use of short lived connections. Each time the query MCP tool is used a temporary, reaodnly connection is created + query is executed + connection is closed. This feature was motivated by a workflow where DBT was for modeling data within duckdb and then an MCP client (Windsurf/Cline/Claude/Cursor) was used for exploring the database. The short lived connections allow each tool to run and then release their connection, allowing the next tool to connect.
Example Queries
Once configured, you can e.g. ask Claude to run queries like:
- "Create a new database and table in MotherDuck"
- "Query data from my local CSV file"
- "Join data from my local DuckDB database with a table in MotherDuck"
- "Analyze data stored in Amazon S3"
Testing
The server is designed to be run by tools like Claude Desktop and Cursor, but you can start it manually for testing purposes. When testing the server manually, you can specify which database to connect to using the --db-path
parameter:
- Default MotherDuck database:
- To connect to the default MotherDuck database, you will need to pass the auth token using the
--motherduck-token
parameter.
- To connect to the default MotherDuck database, you will need to pass the auth token using the
- Specific MotherDuck database:
- Local DuckDB database:
- In-memory database:
If you don't specify a database path but have set the motherduck_token
environment variable, the server will automatically connect to the default MotherDuck database (md:
).
Running in SSE mode
The server could also be running SSE mode using supergateway
by running the following command:
And you can point your clients such as Claude Desktop, Cursor to this endpoint.
Development configuration
To run the server from a local development environment, use the following configuration:
Troubleshooting
- If you encounter connection issues, verify your MotherDuck token is correct
- For local file access problems, ensure the
--home-dir
parameter is set correctly - Check that the
uvx
command is available in your PATH - If you encounter
spawn uvx ENOENT
errors, try specifying the full path touvx
(output ofwhich uvx
) - In version previous for v0.4.0 we used environment variables, now we use parameters
License
This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.
This server cannot be installed
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
An MCP server for MotherDuck and local DuckDB.
- Resources
- Features
- Components
- Getting Started
- Securing your MCP Server when querying MotherDuck
- Connect to local DuckDB
- Example Queries
- Testing
- Running in SSE mode
- Development configuration
- Troubleshooting
- License
Related Resources
Related MCP Servers
- -securityAlicense-qualityA Model Context Protocol (MCP) server implementation for DuckDB, providing database interaction capabilities through MCP tools. It would be interesting to have LLM analyze it. DuckDB is suitable for local analysis.Last updated -5105PythonMIT License
- AsecurityAlicenseAqualityAn MCP server that provides tools for interacting with Supabase databases, storage, and edge functions.Last updated -1441JavaScriptMIT License
- -securityAlicense-qualityUniversal database MCP server connecting to MySQL, PostgreSQL, SQLite, DuckDB and etc.Last updated -3548TypeScriptMIT License
- GoApache 2.0