by motherduckdb
Enables SQL analytics on DuckDB and MotherDuck databases via a Model Context Protocol server, allowing AI assistants and IDEs to query data directly.
Provides a Model Context Protocol (MCP) server that connects to local DuckDB files or cloud‑hosted MotherDuck instances, exposing a single query tool so AI assistants, IDE extensions, and other clients can run SQL against any size of data.
uv (or uvx) – the preferred package runner.uvx mcp-server-motherduck --transport stream --db-path md: --motherduck-token YOUR_TOKEN
--db-path to point to a local DuckDB file (/path/to.db), an in‑memory database (:memory:), or md: for MotherDuck.--read-only for safe concurrent reads, --saas-mode for tighter security, and --json-response when using HTTP streaming.stdio, sse, and stream modes for local or networked use.Q: Do I need a local DuckDB installation? A: No. The server bundles DuckDB; it can create an in‑memory database on the fly.
Q: How do I authenticate to MotherDuck?
A: Provide a token via --motherduck-token or set the MOTHERDUCK_TOKEN environment variable.
Q: Can I run the server behind a firewall?
A: Yes. Use --transport sse with a custom port and expose only the needed endpoint.
Q: What is the purpose of --read-only?
A: It creates short‑lived read‑only connections, allowing many tools to query concurrently without locking.
Q: How do I enable JSON responses?
A: Add the --json-response flag when using the stream transport.
An MCP server implementation that interacts with DuckDB and MotherDuck databases, providing SQL analytics capabilities to AI Assistants and IDEs.
The server provides one prompt:
duckdb-motherduck-initial-prompt: A prompt to initialize a connection to DuckDB or MotherDuck and start working with itThe server offers one tool:
query: Execute a SQL query on the DuckDB or MotherDuck database
query (string, required): The SQL query to executeAll interactions with both DuckDB and MotherDuck are done through writing SQL queries.
The MCP server supports the following parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
--transport |
Choice | stdio |
Transport type. Options: stdio, sse, stream |
--port |
Integer | 8000 |
Port to listen on for sse and stream transport mode |
--db-path |
String | md: |
Path to local DuckDB database file or MotherDuck database |
--motherduck-token |
String | None |
Access token to use for MotherDuck database connections (uses motherduck_token env var by default) |
--read-only |
Flag | False |
Flag for connecting to DuckDB or MotherDuck in read-only mode. For DuckDB it uses short-lived connections to enable concurrent access |
--home-dir |
String | None |
Home directory for DuckDB (uses HOME env var by default) |
--saas-mode |
Flag | False |
Flag for connecting to MotherDuck in SaaS mode. (disables filesystem and write permissions for local DuckDB) |
--json-response |
Flag | False |
Enable JSON responses for HTTP stream. Only supported for stream transport |
# Connect to local DuckDB file in read-only mode with stream transport mode
uvx mcp-server-motherduck --transport stream --db-path /path/to/local.db --read-only
# Connect to MotherDuck with token with stream transport mode
uvx mcp-server-motherduck --transport stream --db-path md: --motherduck-token YOUR_TOKEN
# Connect to local DuckDB file in read-only mode with stream transport mode
uvx mcp-server-motherduck --transport stream --db-path /path/to/local.db --read-only
# Connect to MotherDuck in SaaS mode for enhanced security with stream transport mode
uvx mcp-server-motherduck --transport stream --db-path md: --motherduck-token YOUR_TOKEN --saas-mode
uv installed, you can install it using pip install uv or brew install uvIf you plan to use the MCP with Claude Desktop or any other MCP comptabile client, the client need to be installed.
Install Cursor from cursor.com/downloads if you haven't already
Open Cursor:
mcp.json file to which you add the following configuration:{
"mcpServers": {
"mcp-server-motherduck": {
"command": "uvx",
"args": [
"mcp-server-motherduck",
"--db-path",
"md:",
"--motherduck-token",
"<YOUR_MOTHERDUCK_TOKEN_HERE>"
]
}
}
}
For the quickest installation, click one of the "Install with UV" buttons at the top.
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).
{
"mcp": {
"inputs": [
{
"type": "promptString",
"id": "motherduck_token",
"description": "MotherDuck Token",
"password": true
}
],
"servers": {
"motherduck": {
"command": "uvx",
"args": [
"mcp-server-motherduck",
"--db-path",
"md:",
"--motherduck-token",
"${input:motherduck_token}"
]
}
}
}
}
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.
{
"inputs": [
{
"type": "promptString",
"id": "motherduck_token",
"description": "MotherDuck Token",
"password": true
}
],
"servers": {
"motherduck": {
"command": "uvx",
"args": [
"mcp-server-motherduck",
"--db-path",
"md:",
"--motherduck-token",
"${input:motherduck_token}"
]
}
}
}
Install Claude Desktop from claude.ai/download if you haven't already
Open the Claude Desktop configuration file:
claude_desktop_config.json:{
"mcpServers": {
"mcp-server-motherduck": {
"command": "uvx",
"args": [
"mcp-server-motherduck",
"--db-path",
"md:",
"--motherduck-token",
"<YOUR_MOTHERDUCK_TOKEN_HERE>"
]
}
}
}
Important Notes:
YOUR_MOTHERDUCK_TOKEN_HERE with your actual MotherDuck tokenClaude Code supports MCP servers through CLI commands or JSON configuration. Here are two ways to set it up:
Add the MotherDuck MCP server directly using the Claude Code CLI:
claude mcp add mcp-server-motherduck uvx mcp-server-motherduck -- --db-path md: --motherduck-token <YOUR_MOTHERDUCK_TOKEN_HERE>
Add the server using a JSON configuration:
claude mcp add-json mcp-server-motherduck '{
"command": "uvx",
"args": [
"mcp-server-motherduck",
"--db-path",
"md:",
"--motherduck-token",
"<YOUR_MOTHERDUCK_TOKEN_HERE>"
]
}'
Scoping Options:
--local (default) for project-specific configuration--project to share the configuration with your team via .mcp.json--user to make the server available across all your projectsImportant Notes:
YOUR_MOTHERDUCK_TOKEN_HERE with your actual MotherDuck token${MOTHERDUCK_TOKEN} if you've set the environment variableIf 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
{
"mcpServers": {
"mcp-server-motherduck": {
"command": "uvx",
"args": [
"mcp-server-motherduck",
"--db-path",
"md:",
"--motherduck-token",
"<YOUR_READ_SCALING_TOKEN_HERE>",
"--saas-mode"
]
}
}
}
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:
{
"mcpServers": {
"mcp-server-motherduck": {
"command": "uvx",
"args": [
"mcp-server-motherduck",
"--db-path",
":memory:"
]
}
}
}
Local DuckDB file:
{
"mcpServers": {
"mcp-server-motherduck": {
"command": "uvx",
"args": [
"mcp-server-motherduck",
"--db-path",
"/path/to/your/local.db"
]
}
}
}
Local DuckDB file in readonly mode:
{
"mcpServers": {
"mcp-server-motherduck": {
"command": "uvx",
"args": [
"mcp-server-motherduck",
"--db-path",
"/path/to/your/local.db",
"--read-only"
]
}
}
}
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.
Once configured, you can e.g. ask Claude to run queries like:
The server can run in SSE mode in two ways:
Run the server directly in SSE mode using the --transport sse flag:
uvx mcp-server-motherduck --transport sse --port 8000 --db-path md: --motherduck-token <your_motherduck_token>
This will start the server listening on the specified port (default 8000) and you can point your clients directly to this endpoint.
Alternatively, you can run SSE mode using supergateway:
npx -y supergateway --stdio "uvx mcp-server-motherduck --db-path md: --motherduck-token <your_motherduck_token>"
Both methods allow you to point your clients such as Claude Desktop, Cursor to the SSE endpoint.
To run the server from a local development environment, use the following configuration:
{
"mcpServers": {
"mcp-server-motherduck": {
"command": "uv",
"args": [
"--directory",
"/path/to/your/local/mcp-server-motherduck",
"run",
"mcp-server-motherduck",
"--db-path",
"md:",
"--motherduck-token",
"<YOUR_MOTHERDUCK_TOKEN_HERE>"
]
}
}
}
--home-dir parameter is set correctlyuvx command is available in your PATHspawn uvx ENOENT errors, try specifying the full path to uvx (output of which uvx)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.
mcp-name: io.github.motherduckdb/mcp-server-motherduck
Please log in to share your review and rating for this MCP.
Explore related MCPs that share similar capabilities and solve comparable challenges
by googleapis
An MCP server that streamlines database tool development by handling connection pooling, authentication, observability, and secure access, allowing agents to interact with databases via natural language.
by bytebase
Provides a universal gateway that lets MCP‑compatible clients explore and query MySQL, PostgreSQL, SQL Server, MariaDB, and SQLite databases through a single standardized interface.
by designcomputer
Enables secure interaction with MySQL databases via the Model Context Protocol, allowing AI applications to list tables, read contents, and execute queries safely.
by benborla
Provides read‑only access to MySQL databases for large language models, allowing schema inspection and safe execution of SQL queries.
by neo4j-contrib
Enables natural‑language interaction with Neo4j databases, allowing large language models to query, modify, and manage graph data through multiple transport modes.
by mongodb-js
Provides a Model Context Protocol server that enables interaction with MongoDB databases and MongoDB Atlas clusters through a unified API.
by ClickHouse
Enables AI assistants to run read‑only ClickHouse queries, list databases and tables, and execute embedded chDB queries through an MCP interface.
by neondatabase
Interact with Neon Postgres databases using natural language commands through the Model Context Protocol, enabling conversational database creation, migration, and query execution.
by chroma-core
Offers an MCP server exposing Chroma's vector database capabilities for LLM applications, supporting collection and document management, multiple embedding functions, and flexible client types such as in‑memory, persistent, HTTP, and cloud.