{"id":9100,"library":"mcp-server-motherduck","title":"MotherDuck Connector Protocol Server","description":"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.","status":"active","version":"1.0.4","language":"en","source_language":"en","source_url":"https://github.com/motherduck-api/mcp-server-motherduck","tags":["fastapi","duckdb","motherduck","server","database-connector","mcp"],"install":[{"cmd":"pip install mcp-server-motherduck","lang":"bash","label":"Install core server"}],"dependencies":[{"reason":"Web framework for the server API.","package":"fastapi","optional":false},{"reason":"ASGI server to run the FastAPI application.","package":"uvicorn[standard]","optional":false},{"reason":"Core database engine for local and MotherDuck connections.","package":"duckdb","optional":false},{"reason":"Enhanced logging.","package":"loguru","optional":false},{"reason":"Environment variable management.","package":"python-dotenv","optional":false},{"reason":"Client library for connecting to MotherDuck.","package":"motherduckdb","optional":false}],"imports":[{"note":"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.","symbol":"app","correct":"from mcp_server_motherduck.main import app"}],"quickstart":{"code":"import os\n\n# Set environment variables for MotherDuck (or DUCKDB_PATH for local DuckDB)\n# For local DuckDB: os.environ['DUCKDB_PATH'] = '/path/to/my_local.duckdb'\n# For MotherDuck: os.environ['MD_TOKEN'] = os.environ.get('MD_TOKEN', 'YOUR_MOTHERDUCK_TOKEN')\n\nprint(\"To run the MCP server:\")\nprint(\"1. Ensure mcp-server-motherduck and uvicorn are installed: pip install mcp-server-motherduck uvicorn[standard]\")\nprint(\"2. Run the server from your terminal:\")\nprint(\"   uvicorn mcp_server_motherduck.main:app --host 0.0.0.0 --port 8000\")\nprint(\"\\nOnce running, you can connect using the DuckDB CLI:\")\nprint(\"   duckdb 'md:http://localhost:8000/'\")\nprint(\"   -- or if using a local DuckDB file --\")\nprint(\"   duckdb 'md:http://localhost:8000/?duckdb_path=/path/to/my_local.duckdb'\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Specify a different port when running `uvicorn`, e.g., `uvicorn mcp_server_motherduck.main:app --host 0.0.0.0 --port 8001`.","message":"The default server port (8000) might already be in use by another application. This will prevent the server from starting.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Review the source code and consider implementing robust error handling, authentication, and scaling strategies if deploying in a critical production environment.","message":"The server is labeled as an 'example implementation'. While functional, it might require additional hardening or features for production use cases.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install uvicorn with its standard dependencies: `pip install 'uvicorn[standard]'`","cause":"Uvicorn, the ASGI server, is not installed.","error":"ModuleNotFoundError: No module named 'uvicorn'"},{"fix":"Set the `MD_TOKEN` environment variable with your MotherDuck token before starting the server. Example: `export MD_TOKEN='YOUR_TOKEN_HERE'`.","cause":"The `MD_TOKEN` environment variable, required for MotherDuck connections, is not set or is invalid.","error":"duckdb.duckdb.ConnectionException: Unable to connect to MotherDuck. Please set the 'MD_TOKEN' environment variable."},{"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).","cause":"Another application is already listening on the default port (8000).","error":"ERROR: [Errno 98] Address already in use"},{"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.","cause":"The `DUCKDB_PATH` environment variable for local DuckDB is invalid, or the `MD_TOKEN` for MotherDuck is incorrect or expired.","error":"Error response from server: {'detail': 'Invalid DuckDB path or MotherDuck token'}"}]}