mcp -duckdb

This MCP server provides a DuckDB-backed database interaction tool accessible through the MCP protocol. The server exposes a single tool named query, which accepts any valid DuckDB SQL statement and returns the results as text or a confirmation message for non-query operations (e.g., CREATE, INSERT). When running in read-only mode, the underlying DuckDB connection enforces read-only access, preventing any write operations. To use the server, ensure the MCP server process is started with the correct database path, then invoke the query tool with your SQL commands. For Claude Desktop integration, configure the server via uvx with the --db-path pointing to your DuckDB file, and optionally enable read-only mode to restrict write access. The MCP inspector can help debug request/response flow, tool execution, and server state during development.

Prerequisites:\n- Python with the uv package manager\n- DuckDB Python package (duckdb)\n- MCP server dependencies\n- Smithery (for automatic installation via Smithery) or a local Python environment with uvx\n\nInstallation steps:\n1) Install the MCP server client/host tooling via Smithery (recommended):\nbash\nnpx -y @smithery/cli install mcp-server-duckdb --client claude\n\n2) Ensure Python and uv are available on your system. If you don’t use Smithery, install uvx manually in a Python environment and ensure the mcp-server-duckdb package is accessible.\n3) Prepare the DuckDB database file path. Create directories as needed, e.g.:\nbash\nmkdir -p ~/mcp-server-duckdb/data\n\n4) Run the MCP server (example using uvx):\nbash\nuvx mcp-server-duckdb --db-path ~/mcp-server-duckdb/data/data.db\n\n5) If integrating with Claude Desktop, update the configuration with the appropriate db-path as shown in the Claude Desktop integration instructions.\n6) Optional: verify server startup and accessibility by issuing a test query via your MCP client.\n

Tips and notes:\n- The --db-path path will be created if it does not exist unless the read-only flag is used and the file is missing. In read-only mode, if the database file does not exist, startup will fail.\n- The server exposes a single tool named query for performing any SQL operation. Modern LLMs can generate the needed SQL for SELECT, CREATE, INSERT, UPDATE, DELETE, etc., so one generic tool is sufficient.\n- When running with read-only protection, you can safely allow LLMs to request data retrieval without risking data modification.\n- If you need faster repeated queries, enabling --keep-connection may reuse a single DuckDB connection for the session.\n- The integration with Claude Desktop requires correct JSON configuration in Claude’s config and a valid path to the database. Ensure environment paths (like ~) expand correctly in your shell or replace with full paths in production.\n