{"id":9926,"library":"mcp-server-duckdb","title":"DuckDB MCP Server","description":"mcp-server-duckdb is a Python library that provides a Micro-Capability Platform (MCP) server exposing a DuckDB database via HTTP. It allows clients to execute SQL queries against a DuckDB instance, supporting both read and write operations, and a read-only mode. The current version is 1.1.0, with an active, feature-driven release cadence.","status":"active","version":"1.1.0","language":"en","source_language":"en","source_url":"https://github.com/ktanaka101/mcp-server-duckdb","tags":["duckdb","server","api","database","data-connector","fastapi","sql"],"install":[{"cmd":"pip install mcp-server-duckdb","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core database engine for query execution.","package":"duckdb"},{"reason":"Web framework used to build the HTTP server API.","package":"fastapi"},{"reason":"ASGI server to run the FastAPI application.","package":"uvicorn"}],"imports":[{"note":"Primarily intended for CLI execution, but can be called programmatically to start the server. Best practice is to use the `mcp-server-duckdb` CLI command.","symbol":"run_server","correct":"from mcp_server_duckdb.main import run_server"},{"note":"Use to create the FastAPI application instance for testing or embedding within another ASGI application. Requires a `Config` object.","symbol":"create_app","correct":"from mcp_server_duckdb.server import create_app"}],"quickstart":{"code":"import os\nimport requests\nfrom subprocess import Popen, PIPE, TimeoutExpired\nimport time\n\n# Start the server in a separate process\n# For simplicity, we use a temporary in-memory database here\n# In production, specify a persistent .duckdb file, e.g., --db-path my_database.duckdb\nprint('Starting mcp-server-duckdb...')\nserver_process = Popen(['mcp-server-duckdb', '--port', '8001'], stdout=PIPE, stderr=PIPE)\ntime.sleep(2) # Give the server a moment to start\n\n# Example: Send a query\ntry:\n    # Create a table\n    response = requests.post(\n        'http://localhost:8001/queries',\n        json={'query': \"CREATE TABLE users (id INTEGER, name VARCHAR);\"}\n    )\n    response.raise_for_status()\n    print('CREATE TABLE response:', response.json())\n\n    # Insert data\n    response = requests.post(\n        'http://localhost:8001/queries',\n        json={'query': \"INSERT INTO users VALUES (1, 'Alice'), (2, 'Bob');\"}\n    )\n    response.raise_for_status()\n    print('INSERT INTO response:', response.json())\n\n    # Select data\n    response = requests.post(\n        'http://localhost:8001/queries',\n        json={'query': \"SELECT * FROM users;\"}\n    )\n    response.raise_for_status()\n    print('SELECT * response:', response.json())\n\nexcept requests.exceptions.RequestException as e:\n    print(f\"Error communicating with server: {e}\")\nfinally:\n    # Terminate the server process\n    print('Stopping mcp-server-duckdb...')\n    server_process.terminate()\n    try:\n        stdout, stderr = server_process.communicate(timeout=5)\n        print('Server stdout:', stdout.decode())\n        print('Server stderr:', stderr.decode())\n    except TimeoutExpired:\n        server_process.kill()\n        stdout, stderr = server_process.communicate()\n        print('Server (killed) stdout:', stdout.decode())\n        print('Server (killed) stderr:', stderr.decode())\n","lang":"python","description":"This quickstart demonstrates how to start the `mcp-server-duckdb` server programmatically and then interact with it using HTTP requests. It creates a simple table, inserts data, and queries it. For persistent databases, specify a file path with `--db-path` when starting the server."},"warnings":[{"fix":"Migrate all database interactions to use the `/queries` endpoint with a single `query` parameter in the request body.","message":"The API for database queries was consolidated into a single `/queries` endpoint. Before v1.0.0, there were separate endpoints for read and write operations (e.g., `/read-query`, `/write-query`).","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"Update to v1.1.0 or later and start the server with the `--keep-connection` flag to maintain a persistent DuckDB connection across queries.","message":"Temporary tables and macros created within a session will not persist across multiple queries by default. Each query opens and closes a new DuckDB connection.","severity":"gotcha","affected_versions":"<1.1.0"},{"fix":"Ensure the server is not started with `--readonly` if write operations are intended. If using an older version (<0.2.2), fix for readonly logic might be necessary.","message":"Attempting write operations (e.g., INSERT, UPDATE, CREATE TABLE) when the server is started with the `--readonly` flag will result in an error.","severity":"gotcha","affected_versions":">=0.2.0"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Ensure the package is installed using `pip install mcp-server-duckdb` and that your shell's PATH includes the directory where pip installs scripts (e.g., `~/.local/bin` on Linux/macOS or `Scripts` directory in your Python environment on Windows).","cause":"The `mcp-server-duckdb` package is not installed, or its executable script is not in your system's PATH.","error":"Command 'mcp-server-duckdb' not found"},{"fix":"If you intend to perform write operations, restart the `mcp-server-duckdb` server without the `--readonly` flag.","cause":"The server was started with the `--readonly` flag, preventing any data modification or schema changes.","error":"RuntimeError: Attempted to write to a database in read-only mode."},{"fix":"Ensure your POST request to `/queries` sends a JSON body like `{'query': 'YOUR_SQL_QUERY_HERE'}` and the `Content-Type` header is `application/json`.","cause":"The request body for the `/queries` endpoint is malformed or missing the required `query` field.","error":"requests.exceptions.HTTPError: 422 Unprocessable Entity (or similar for missing query parameter)"}]}