MCP Server Duckdb

1# mcp-server-duckdb
2 
3[![PyPI - Version](https://img.shields.io/pypi/v/mcp-server-duckdb)](https://pypi.org/project/mcp-server-duckdb/)
4[![PyPI - License](https://img.shields.io/pypi/l/mcp-server-duckdb)](LICENSE)
5[![smithery badge](https://smithery.ai/badge/mcp-server-duckdb)](https://smithery.ai/server/mcp-server-duckdb)
6 
7A Model Context Protocol (MCP) server implementation for DuckDB, providing database interaction capabilities through MCP tools.
8It would be interesting to have LLM analyze it. DuckDB is suitable for local analysis.
9 
10<a href="https://glama.ai/mcp/servers/fwggl49w22"><img width="380" height="200" src="https://glama.ai/mcp/servers/fwggl49w22/badge" alt="mcp-server-duckdb MCP server" /></a>
11 
12## Overview
13 
14This server enables interaction with a DuckDB database through the Model Context Protocol, allowing for database operations like querying, table creation, and schema inspection.
15 
16## Components
17 
18### Resources
19 
20Currently, no custom resources are implemented.
21 
22### Prompts
23 
24Currently, no custom prompts are implemented.
25 
26### Tools
27 
28The server implements the following database interaction tool:
29 
30- **query**: Execute any SQL query on the DuckDB database
31  - **Input**: `query` (string) - Any valid DuckDB SQL statement
32  - **Output**: Query results as text (or success message for operations like CREATE/INSERT)
33 
34> [!NOTE]
35> The server provides a single unified `query` function rather than separate specialized functions, as modern LLMs can generate appropriate SQL for any database operation (SELECT, CREATE TABLE, JOIN, etc.) without requiring separate endpoints.
36 
37> [!NOTE]
38> When the server is running in `readonly` mode, DuckDB's native readonly protection is enforced.
39> This ensures that the Language Model (LLM) cannot perform any write operations (CREATE, INSERT, UPDATE, DELETE), maintaining data integrity and preventing unintended changes.
40 
41## Configuration
42 
43### Required Parameters
44 
45- **db-path** (string): Path to the DuckDB database file
46  - The server will automatically create the database file and parent directories if they don't exist
47  - If `--readonly` is specified and the database file doesn't exist, the server will fail to start with an error
48 
49### Optional Parameters
50 
51- **--readonly**: Run server in read-only mode (default: `false`)
52  - **Description**: When this flag is set, the server operates in read-only mode. This means:
53    - The DuckDB database will be opened with `read_only=True`, preventing any write operations.
54    - If the specified database file does not exist, it **will not** be created.
55    - **Security Benefit**: Prevents the Language Model (LLM) from performing any write operations, ensuring that the database remains unaltered.
56  - **Reference**: For more details on read-only connections in DuckDB, see the [DuckDB Python API documentation](https://duckdb.org/docs/api/python/dbapi.html#read_only-connections).
57- **--keep-connection**: Re-uses a single DuckDB connection mode (default: `false`)
58  - **Description**: When this flag is set, Re-uses a single DuckDB connection for the entire server lifetime. Enables TEMP objects & slightly faster queries, but can hold an exclusive lock on the file.
59 
60## Installation
61 
62### Installing via Smithery
63 
64To install DuckDB Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/mcp-server-duckdb):
65 
66```bash
67npx -y @smithery/cli install mcp-server-duckdb --client claude
68```
69 
70### Claude Desktop Integration
71 
72Configure the MCP server in Claude Desktop's configuration file:
73 
74#### MacOS
75Location: `~/Library/Application Support/Claude/claude_desktop_config.json`
76 
77#### Windows
78Location: `%APPDATA%/Claude/claude_desktop_config.json`
79 
80```json
81{
82  "mcpServers": {
83    "duckdb": {
84      "command": "uvx",
85      "args": [
86        "mcp-server-duckdb",
87        "--db-path",
88        "~/mcp-server-duckdb/data/data.db"
89      ]
90    }
91  }
92}
93```
94 
95* Note: `~/mcp-server-duckdb/data/data.db` should be replaced with the actual path to the DuckDB database file.
96 
97## Development
98 
99### Prerequisites
100 
101- Python with `uv` package manager
102- DuckDB Python package
103- MCP server dependencies
104 
105### Debugging
106 
107Debugging MCP servers can be challenging due to their stdio-based communication. We recommend using the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) for the best debugging experience.
108 
109#### Using MCP Inspector
110 
1111. Install the inspector using npm:
112```bash
113npx @modelcontextprotocol/inspector uv --directory ~/codes/mcp-server-duckdb run mcp-server-duckdb --db-path ~/mcp-server-duckdb/data/data.db
114```
115 
1162. Open the provided URL in your browser to access the debugging interface
117 
118The inspector provides visibility into:
119- Request/response communication
120- Tool execution
121- Server state
122- Error messages
123