Registry / database / mcp-server-motherduck

mcp-server-motherduck

library1.0.7pypypi✓ verified 80d ago

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.

database web-framework http-networking observability

pip install mcp-server-motherduck

package ↗

INSTALL

IMPORT

SIG · MCP-SERVER-MOTHERD

mcp-server-motherduck

databasepythonv1.0.7

Install

12.3s avg

Import

—

Disk

174MB

Pass rate

4/ 10

Env Coverage4 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.0.7 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

glibc

py 3.10

✕ build_error

✓ 14.25s

py 3.11

✕ build_error

✓ 13.4s

py 3.12

✕ build_error

✓ 10.75s

py 3.13

✕ build_error

✓ 10.85s

py 3.9

✕ build_error

174MB installed

● package 174MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

create_mcp_server

✓ from mcp_server_motherduck import create_mcp_server

✗ from mcp_server_motherduck import app

SERVER_LOCALHOST

✓ from mcp_server_motherduck import SERVER_LOCALHOST

SERVER_VERSION

✓ from mcp_server_motherduck import SERVER_VERSION

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'")

mcp-server-motherduck --version

Debug

Known issues

gotchaConfiguration 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.

affects: All versions

gotchaThis 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.

affects: All versions

gotchaThe 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`.

affects: All versions

gotchaThe 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.

affects: All versions

Upgrade

Version history

1.0.7latest on PyPI · released Jun 9, 2026

Audit

Dependencies

fastapirequiredWeb framework for the server API.

uvicorn[standard]requiredASGI server to run the FastAPI application.

duckdbrequiredCore database engine for local and MotherDuck connections.

logururequiredEnhanced logging.

python-dotenvrequiredEnvironment variable management.

motherduckdbrequiredClient library for connecting to MotherDuck.

Agent activity

21 hits · last 30 days

node

OpenAI (training)

Resources

packagehttps://pypi.org/project/mcp-server-motherduck/ ↗