---
warning: DO NOT CHANGE THIS MANUALLY, THIS IS GENERATED BY https://github.com/duckdb/community-extensions repository, check README there
title: duckdb_mcp
excerpt: |
DuckDB Community Extensions
Model Context Protocol (MCP) extension for DuckDB that enables seamless integration between SQL databases and MCP servers. Provides both client capabilities for accessing remote MCP resources via SQL and server capabilities for exposing database content as MCP resources.
extension:
name: duckdb_mcp
description: Model Context Protocol (MCP) extension for DuckDB that enables seamless integration between SQL databases and MCP servers. Provides both client capabilities for accessing remote MCP resources via SQL and server capabilities for exposing database content as MCP resources.
version: 2.4.0
language: C++
build: cmake
license: Apache-2.0
requires_toolchains: ""
maintainers:
- teaguesterling
repo:
github: teaguesterling/duckdb_mcp
ref: 6b2b1dc899e1b5834ed6ee2f574e309f445e23b1
variegata: 6b2b1dc899e1b5834ed6ee2f574e309f445e23b1
# ref == ref_next == variegata (deliberate): v2.4.0 builds against DuckDB v2.0.0 and
# v1.5.6 from one tree. ref_next == ref makes test_against_latest build+test the
# shipped release on v2.0-cyanoptera, rather than skipping it.
ref_next: 6b2b1dc899e1b5834ed6ee2f574e309f445e23b1
docs:
hello_world: |
-- Load the MCP extension
LOAD 'duckdb_mcp';
-- Connect to an MCP server using stdio transport
ATTACH 'python3' AS data_server (
TYPE mcp,
TRANSPORT 'stdio',
ARGS '["path/to/server.py"]'
);
-- Access remote data via MCP protocol
SELECT * FROM read_csv('mcp://data_server/file:///data.csv');
SELECT * FROM read_json('mcp://data_server/api://endpoint');
-- List available resources on the server
SELECT mcp_list_resources('data_server');
-- Execute tools on the MCP server
SELECT mcp_call_tool('data_server', 'process_data', '{"table": "sales"}');
-- Server mode: Start an MCP server to expose database content
SELECT mcp_server_start('stdio', 'localhost', 0, '{}');
-- or mcp_server_start('stdio')
-- Publish database tables as MCP resources
CREATE TABLE products AS SELECT 'Widget' as name, 10.99 as price;
SELECT mcp_publish_table('products', 'data://tables/products', 'json');
extended_description: |
DuckDB MCP Extension bridges SQL databases with the Model Context Protocol (MCP), enabling bidirectional integration between DuckDB and MCP servers. The extension operates in dual modes: as an MCP client for accessing remote resources and as an MCP server for exposing database content.
See the [README.md](https://github.com/teaguesterling/duckdb_mcp/blob/main/README.md) for more details.
**MCP Client Capabilities**: Connect to MCP servers using multiple transport protocols (stdio, TCP, WebSocket) and access remote resources directly in SQL queries. Use the `mcp://` URI scheme with standard DuckDB functions like `read_csv()`, `read_parquet()`, and `read_json()` to seamlessly query remote data sources. Execute remote tools with `mcp_call_tool()` and discover available resources with `mcp_list_resources()`.
**MCP Server Capabilities**: Transform DuckDB into an MCP resource provider by exposing tables, views, and query results as MCP resources. Start an MCP server with `mcp_server_start()`, publish static table snapshots with `mcp_publish_table()`, and create dynamic resources with `mcp_publish_query()` that refresh at configurable intervals.
**Security Framework**: Flexible security models supporting both development and production environments. Development mode offers permissive access for rapid prototyping, while production mode enforces strict allowlists for commands and URLs. Configure security through settings like `allowed_mcp_commands`, `allowed_mcp_urls`, and JSON configuration files.
**Key Client Functions**:
- `mcp_list_resources(server)` - Discover available resources
- `mcp_get_resource(server, uri)` - Retrieve specific resource content
- `mcp_call_tool(server, tool, args)` - Execute remote tools
- `read_csv('mcp://server/uri')` - Read CSV data via MCP
- `read_parquet('mcp://server/uri')` - Read Parquet data via MCP
- `read_json('mcp://server/uri')` - Read JSON data via MCP
**Key Server Functions**:
- `mcp_server_start(transport, host, port, config)` - Start MCP server
- `mcp_server_stop()` - Stop MCP server
- `mcp_server_status()` - Check server status
- `mcp_publish_table(table, uri, format)` - Publish table as resource
- `mcp_publish_query(sql, uri, format, interval)` - Publish query results
- `mcp_publish_execution_tool(name, desc, sql, props, required, bindings)` - Publish execution tools with prepared parameter binding
**State Introspection** (v2.1):
- `mcp_tools()` - Query all published tools as a table
- `mcp_resources()` - Query all published resources as a table
- `mcp_server_config()` - Server configuration as key-value pairs
- `mcp_list_tools()` - No-arg tool listing (works before and after server start)
**v2.0 Highlights**:
- **Execution tools** with multi-statement SQL and per-statement typed parameter binding
- **Typed JSON output** preserving DuckDB types (numbers, booleans) instead of stringifying
- **Prompt/template support** for MCP prompts list and get
- **JSONL and text output formats** alongside JSON and CSV
- **Read-only enforcement** in query, export, and describe tools
- **Per-instance state** replacing global singletons for safe multi-database usage
- Extensive security hardening and bug fixes
The extension implements the complete JSON-RPC 2.0 MCP protocol with support for multiple transport mechanisms. It enables powerful use cases including database federation, remote data access, tool orchestration, and exposing database insights to external MCP-compatible systems. Perfect for integration with AI agents, data pipelines, and distributed analytical workflows.
extension_star_count: 68
extension_star_count_pretty: 68
extension_download_count: 3677
extension_download_count_pretty: 3.7k
image: '/images/community_extensions/social_preview/preview_community_extension_duckdb_mcp.png'
layout: community_extension_doc
---
### Compatibility Matrix
This table covers all DuckDB releases that have not reached [end-of-life](https://duckdb.org/release_calendar), including LTS releases, and shows the 2 most recent patch releases of each. Older patch releases are not listed, but the extension may be available for them as well.
| Platform | 1.4.4 | 1.4.5 | 1.5.5 | 1.5.6 | 2.0.0 |
| :--- | :---: | :---: | :---: | :---: | :---: |
| Linux AMD64 | ✅ | ✅ | ✅ | ✅ | ✅ |
| Linux ARM64 | ✅ | ✅ | ✅ | ✅ | ✅ |
| macOS AMD64 | ✅ | ✅ | ✅ | ✅ | ❌ |
| macOS ARM64 | ✅ | ✅ | ✅ | ✅ | ✅ |
| Windows AMD64 | ✅ | ✅ | ✅ | ✅ | ✅ |
| Windows ARM64 | ❌ | ❌ | ❌ | ❌ | ❌ |
| WebAssembly | ✅ | ✅ | ✅ | ✅ | ✅ |
### Installing and Loading
```sql
INSTALL {{ page.extension.name }} FROM community;
LOAD {{ page.extension.name }};
```
{% if page.docs.hello_world %}
### Example
```sql
{{ page.docs.hello_world }}```
{% endif %}
{% if page.docs.extended_description %}
### About {{ page.extension.name }}
{{ page.docs.extended_description }}
{% endif %}
### Added Functions
| function_name | function_type | description | comment | examples |
|------------------------------|---------------|-----------------------------------------------------------------------------------------|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| mcp_call_tool | scalar | Call a tool provided by an attached MCP server. | NULL | [mcp_call_tool('server', 'tool_name', '{"arg": 1}')] |
| mcp_config_begin | pragma | NULL | NULL | |
| mcp_config_end | pragma | NULL | NULL | |
| mcp_get_diagnostics | scalar | Get internal diagnostics and connection states for the MCP extension. | NULL | [mcp_get_diagnostics()] |
| mcp_get_prompt | scalar | Get a rendered prompt template from an attached MCP server. | NULL | [mcp_get_prompt('server', 'prompt_name', '{"arg": 1}')] |
| mcp_get_resource | scalar | Get content of a resource from an attached MCP server. | NULL | [mcp_get_resource('server', 'resource://uri')] |
| mcp_list_prompt_templates | scalar | List all registered prompt templates. | NULL | [mcp_list_prompt_templates()] |
| mcp_list_prompts | scalar | List available prompt templates from an attached MCP server. | NULL | [mcp_list_prompts('server')] |
| mcp_list_resources | scalar | List available resources from an attached MCP server. | NULL | [mcp_list_resources('server')] |
| mcp_list_tools | scalar | List available tools from an attached MCP server. | NULL | [mcp_list_tools('server')] |
| mcp_list_tools | table | List registered MCP tools on the embedded server (alias for mcp_tools). | NULL | [SELECT * FROM mcp_list_tools()] |
| mcp_publish_execution_tool | pragma | NULL | NULL | |
| mcp_publish_execution_tool | scalar | Publish an execution tool that runs SQL queries against DuckDB with parameter bindings. | NULL | [mcp_publish_execution_tool('exec_query', 'Execute parameterized query', 'SELECT $val', '{"val": {"type": "string"{% raw %}}}{% endraw %}', '["val"]', '{"val": "VARCHAR"}')] |
| mcp_publish_query | pragma | NULL | NULL | |
| mcp_publish_query | scalar | Publish a DuckDB SQL query as an MCP resource. | NULL | [mcp_publish_query('top_users', 'SELECT * FROM users LIMIT 10', 'Top 10 users', 300)] |
| mcp_publish_resource | pragma | NULL | NULL | |
| mcp_publish_resource | scalar | Publish static text or JSON content as an MCP resource. | NULL | [mcp_publish_resource('resource://docs', 'Documentation text', 'text/plain', 'Doc resource')] |
| mcp_publish_table | pragma | NULL | NULL | |
| mcp_publish_table | scalar | Publish a DuckDB table or view as an MCP resource. | NULL | [mcp_publish_table('my_table', 'resource://my_table', 'My data table')] |
| mcp_publish_tool | pragma | NULL | NULL | |
| mcp_publish_tool | scalar | Publish a parameterized SQL query as an MCP tool. | NULL | [mcp_publish_tool('get_user', 'Get user by ID', 'SELECT * FROM users WHERE id = $id', '{"id": {"type": "integer"{% raw %}}}{% endraw %}', '["id"]')] |
| mcp_reconnect_server | scalar | Reconnect to an attached MCP server. | NULL | [mcp_reconnect_server('server')] |
| mcp_register_prompt_template | pragma | NULL | NULL | |
| mcp_register_prompt_template | scalar | Register a prompt template with parameters for the MCP server. | NULL | [mcp_register_prompt_template('greeting', 'Greeting prompt', 'Hello {% raw %}{{{% endraw %}name{% raw %}}}{% endraw %}!')] |
| mcp_render_prompt_template | scalar | Render a registered prompt template with arguments. | NULL | [mcp_render_prompt_template('greeting', '{"name": "Alice"}')] |
| mcp_resources | table | List registered MCP resources on the embedded server. | NULL | [SELECT * FROM mcp_resources()] |
| mcp_server_config | table | Get configuration key-value pairs of the embedded MCP server. | NULL | [SELECT * FROM mcp_server_config()] |
| mcp_server_health | scalar | Check the health and connection status of an attached MCP server. | NULL | [mcp_server_health('server')] |
| mcp_server_send_request | scalar | Send a JSON-RPC request to the running embedded MCP server. | NULL | [mcp_server_send_request('{"jsonrpc": "2.0", "method": "tools/list", "id": 1}')] |
| mcp_server_start | pragma | NULL | NULL | |
| mcp_server_start | scalar | Start the embedded MCP server. | NULL | [mcp_server_start('stdio')] |
| mcp_server_status | scalar | Get the current running status and statistics of the embedded MCP server. | NULL | [mcp_server_status()] |
| mcp_server_stop | pragma | NULL | NULL | |
| mcp_server_stop | scalar | Stop the embedded MCP server. | NULL | [mcp_server_stop()] |
| mcp_server_test | scalar | Test MCP server protocol handling with a raw JSON-RPC request. | NULL | [mcp_server_test('{"jsonrpc": "2.0", "method": "ping", "id": 1}')] |
| mcp_tools | table | List registered MCP tools on the embedded server. | NULL | [SELECT * FROM mcp_tools()] |
### Overloaded Functions
This extension does not add any function overloads.
### Added Types
This extension does not add any types.
### Added Settings
| name | description | input_type | scope | aliases | typed_value |
|------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------|--------|---------|-------------|
| allowed_mcp_commands | Colon-delimited list of executable paths allowed for MCP servers (security: executable paths only, no arguments) | VARCHAR | GLOBAL | [] | |
| allowed_mcp_urls | Space-delimited list of URL prefixes allowed for MCP servers | VARCHAR | GLOBAL | [] | |
| mcp_allow_all_commands | INSECURE opt-in: when true, allow spawning ANY command if no allowed_mcp_commands allowlist is set. Default false = deny-all (fail-closed). Prefer setting allowed_mcp_commands instead. | BOOLEAN | GLOBAL | [] | false |
| mcp_console_logging | Enable MCP logging to console/stderr | BOOLEAN | GLOBAL | [] | false |
| mcp_disable_serving | Disable MCP server functionality entirely (client-only mode) | BOOLEAN | GLOBAL | [] | false |
| mcp_lock_servers | Lock MCP server configuration to prevent runtime changes (security feature) | BOOLEAN | GLOBAL | [] | false |
| mcp_log_file | Path to MCP log file (empty for no file logging) | VARCHAR | GLOBAL | [] | |
| mcp_log_level | MCP logging level (trace, debug, info, warn, error, off) | VARCHAR | GLOBAL | [] | warn |
| mcp_server_file | Path to MCP server configuration file | VARCHAR | GLOBAL | [] | ./.mcp.json |
| temp_directory | Set the directory to which temporary files are written. | VARCHAR | GLOBAL | [] | post.db.tmp |