MotherDuck Connector Protocol Server

1.0.4 · active · verified Thu Apr 16

This is a sample implementation of the MotherDuck Connector Protocol (MCP) server that allows DuckDB clients to connect to MotherDuck or local DuckDB instances via a lightweight HTTP server. It's built on FastAPI. The current version is 1.0.4, and its release cadence is tied to updates in the MCP specification or the underlying DuckDB/MotherDuck APIs, serving primarily as a reference and bridge.

Common errors

```
ModuleNotFoundError: No module named 'uvicorn'
```
cause Uvicorn, the ASGI server, is not installed.

fix Install uvicorn with its standard dependencies: `pip install 'uvicorn[standard]'`
```
duckdb.duckdb.ConnectionException: Unable to connect to MotherDuck. Please set the 'MD_TOKEN' environment variable.
```
cause The `MD_TOKEN` environment variable, required for MotherDuck connections, is not set or is invalid.

fix Set the `MD_TOKEN` environment variable with your MotherDuck token before starting the server. Example: `export MD_TOKEN='YOUR_TOKEN_HERE'`.
```
ERROR: [Errno 98] Address already in use
```
cause Another application is already listening on the default port (8000).

fix Run the server on a different port: `uvicorn mcp_server_motherduck.main:app --host 0.0.0.0 --port 8001` (or any other free port).
```
Error response from server: {'detail': 'Invalid DuckDB path or MotherDuck token'}
```
cause The `DUCKDB_PATH` environment variable for local DuckDB is invalid, or the `MD_TOKEN` for MotherDuck is incorrect or expired.

fix Verify that the `DUCKDB_PATH` points to a valid .duckdb file or that your `MD_TOKEN` is correct and active. Restart the server after updating.

Warnings

gotcha Configuration requires environment variables `MD_TOKEN` for MotherDuck or `DUCKDB_PATH` for a local DuckDB file. Without these, the server may fail to connect to a backend.
Fix: Set `MD_TOKEN='your_token'` or `DUCKDB_PATH='/path/to/your/db.duckdb'` in your environment before starting the server, or pass them explicitly if embedding.
gotcha This library provides a MotherDuck Connector Protocol *server*, not a client library for direct programmatic interaction with MotherDuck from Python. Its primary use case is to be run as a standalone service.
Fix: Understand that the main interaction is running the `uvicorn` command, not importing and calling functions directly for typical data operations. For direct Python interaction with DuckDB/MotherDuck, use the `duckdb` or `motherduckdb` libraries.
gotcha The default server port (8000) might already be in use by another application. This will prevent the server from starting.
Fix: Specify a different port when running `uvicorn`, e.g., `uvicorn mcp_server_motherduck.main:app --host 0.0.0.0 --port 8001`.
gotcha The server is labeled as an 'example implementation'. While functional, it might require additional hardening or features for production use cases.
Fix: Review the source code and consider implementing robust error handling, authentication, and scaling strategies if deploying in a critical production environment.

Install

pip install mcp-server-motherduck Install core server

Imports

app
```
from mcp_server_motherduck.main import app
```
The 'app' object is the FastAPI application instance. While it can be imported for programmatic integration or testing, the server is typically run via the 'uvicorn' command line tool, which handles this import implicitly.

Quickstart

This quickstart demonstrates how to run the MCP server using `uvicorn` and how to connect to it using the DuckDB CLI. You must have `uvicorn[standard]` installed alongside `mcp-server-motherduck`. Remember to configure MotherDuck via `MD_TOKEN` or a local DuckDB path via `DUCKDB_PATH` environment variables.

import os

# Set environment variables for MotherDuck (or DUCKDB_PATH for local DuckDB)
# For local DuckDB: os.environ['DUCKDB_PATH'] = '/path/to/my_local.duckdb'
# For MotherDuck: os.environ['MD_TOKEN'] = os.environ.get('MD_TOKEN', 'YOUR_MOTHERDUCK_TOKEN')

print("To run the MCP server:")
print("1. Ensure mcp-server-motherduck and uvicorn are installed: pip install mcp-server-motherduck uvicorn[standard]")
print("2. Run the server from your terminal:")
print("   uvicorn mcp_server_motherduck.main:app --host 0.0.0.0 --port 8000")
print("\nOnce running, you can connect using the DuckDB CLI:")
print("   duckdb 'md:http://localhost:8000/'")
print("   -- or if using a local DuckDB file --")
print("   duckdb 'md:http://localhost:8000/?duckdb_path=/path/to/my_local.duckdb'")

view raw JSON →