Which integrations are available for this server?

Provides tools for executing SQL queries, listing databases, tables, and columns, and switching database connections using DuckDB's analytical SQL engine.

How do I use DuckDB MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@DuckDB MCP Server show me the top 5 products by sales" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

DuckDB MCP Server

by MMHK

Overview Schema Related Servers Score Discussions

TypeScript

Local

DuckDB MCP Server

npm version npm downloads npm license GitHub stars npm total downloads

已改名为 mcp-duckdb-local

📖 目录

Related MCP server: DuckDB MCP Server

📝 简介

这是一个本地运行的 Model Context Protocol (MCP) 服务器，允许 AI 助手通过 DuckDB 的强大分析 SQL 引擎访问数据。

🆕 新版本更新

v0.4.0 🚀: 项目重命名

为避免与 npm 上存在的包名冲突，本项目已改用无 scope 的包名 mcp-duckdb-local，可直接发布到 npmjs.com 公共仓库。

✨ 特点

功能	描述
SQL 查询	使用 DuckDB SQL 语法执行读/写查询
目录工具	浏览数据库、表和列
多连接支持	连接到本地文件、内存、S3 或 MotherDuck
读/写模式	可配置的读/写访问控制
安全模式	SaaS 模式限制本地文件系统访问
查询限制	最大行数和字符数限制
查询超时	防止长时间运行的查询
初始化 SQL	启动时执行自定义 SQL

🚀 快速开始

前置要求

Node.js 18+ 或更高版本
yarn >= 4

安装

# 使用 npm
npm install mcp-duckdb-local

# 或使用 pnpm
pnpm add mcp-duckdb-local

# 或使用 yarn
yarn add mcp-duckdb-local

# 使用 npx (无需安装)
npx mcp-duckdb-local --db-path :memory: --read-write

# 使用 yarn dlx (无需安装)
yarn dlx mcp-duckdb-local --db-path :memory: --read-write

在内存模式下运行 (开发模式)

{
  "mcpServers": {
    "DuckDB (内存模式)": {
      "command": "npx",
      "args": ["-y", "mcp-duckdb-local@latest", "--db-path", ":memory:", "--read-write"]
    }
  }
}

注意: Windows 用戶建議使用全局安裝（見下方），避免 npx 執行問題。

連接到本地 DuckDB 文件 (只讀模式)

{
  "mcpServers": {
    "DuckDB (只读)": {
      "command": "npx",
      "args": ["-y", "mcp-duckdb-local@latest", "--db-path", "/absolute/path/to/your.duckdb"]
    }
  }
}

連接到 MotherDuck (读写模式)

{
  "mcpServers": {
    "MotherDuck": {
      "command": "npx",
      "args": ["-y", "mcp-duckdb-local@latest", "--db-path", "md:", "--read-write"],
      "env": {
        "MOTHERDUCK_TOKEN": "<YOUR_TOKEN>"
      }
    }
  }
}

⚠️ Windows 用戶特別說明

在 Windows 上使用 npx 可能會遇到執行問題（Windows Script Host 錯誤）。建議使用以下任一方案：

方案 1：全局安裝（推薦）

npm install -g mcp-duckdb-local

然後在 MCP 配置中使用：

{
  "mcpServers": {
    "DuckDB": {
      "command": "mcp-duckdb-local",
      "args": ["--db-path", "D:/path/to/db.duckdb"]
    }
  }
}

方案 2：使用 npx 時添加 `-y` 標誌

{
  "mcpServers": {
    "DuckDB": {
      "command": "npx",
      "args": ["-y", "mcp-duckdb-local@latest", "--db-path", "D:/path/to/db.duckdb"]
    }
  }
}

方案 3：使用 yarn dlx

{
  "mcpServers": {
    "DuckDB": {
      "command": "yarn",
      "args": ["dlx", "mcp-duckdb-local", "--db-path", "D:/path/to/db.duckdb"]
    }
  }
}

📦 安装

全局安装

npm install -g mcp-duckdb-local
# 或
pnpm add -g mcp-duckdb-local
# 或
yarn global add mcp-duckdb-local

本地安装

npm install mcp-duckdb-mcp --save
# 或
pnpm add mcp-duckdb-local
# 或
yarn add mcp-duckdb-local

📖 使用方法

CLI 命令

# 显示帮助
npx -y mcp-duckdb-local@latest --help

# 連接到本地文件 (只读)
npx -y mcp-duckdb-local@latest --db-path /path/to/database.duckdb

# HTTP 服务器模式
npx -y mcp-duckdb-local@latest --transport http --port 8080

# 全局安裝後直接使用
mcp-duckdb-local --db-path :memory: --read-write

命令行参数

参数	默认值	说明
`--db-path`	`:memory:`	数据库路径 (本地文件, `:memory:`, `md:`, `s3://`)
`--motherduck-token`	env variable	MotherDuck 访问令牌
`--read-write`	`false`	启用写访问
`--motherduck-saas-mode`	`false`	MotherDuck SaaS 模式
`--allow-switch-databases`	`false`	启用数据库切换工具
`--max-rows`	`1024`	最大返回行数
`--max-chars`	`50000`	最大返回字符数
`--query-timeout`	`-1`	查询超时 (秒), -1 禁用
`--init-sql`	`none`	启动时执行的 SQL
`--transport`	`stdio`	传输类型: `stdio` 或 `http`
`--host`	`127.0.0.1`	HTTP 主机
`--port`	`8000`	HTTP 端口
`--home-dir`	system HOME	DuckDB 主目录
`--ephemeral-connections`	`true`	对本地文件使用临时连接

环境变量

变量	说明
`MOTHERDUCK_TOKEN`	MotherDuck 访问令牌
`MCP_DB_PATH`	数据库路径
`MCP_TRANSPORT`	传输类型
`MCP_PORT`	HTTP 端口
`MCP_HOST`	HTTP 主机
`MCP_READ_WRITE`	启用写访问
`MCP_SAAS_MODE`	SaaS 模式
`MCP_ALLOW_SWITCH_DATABASES`	启用数据库切换
`MCP_MAX_ROWS`	最大行数
`MCP_MAX_CHARS`	最大字符数
`MCP_QUERY_TIMEOUT`	查询超时
`HOME`	DuckDB 主目录

🔧 工具

`execute_query`

执行 SQL 查询。

参数:

sql (string, 必需): 要执行的 SQL 查询

示例:

{
  "name": "execute_query",
  "arguments": {
    "sql": "SELECT * FROM my_table LIMIT 10"
  }
}

{
  "success": true,
  "columns": ["id", "name", "created_at"],
  "columnTypes": ["BIGINT", "VARCHAR", "TIMESTAMP"],
  "rows": [
    [1, "Alice", "2024-01-01"],
    [2, "Bob", "2024-01-02"]
  ],
  "rowCount": 2
}

`list_databases`

列出所有可用数据库。

参数: 无

示例:

{
  "name": "list_databases",
  "arguments": {}
}

{
  "success": true,
  "databases": [
    { "name": "memory", "type": "local" },
    { "name": "main", "type": "local" }
  ],
  "databaseCount": 2
}

`list_tables`

列出数据库中的所有表和视图。

参数:

database (string, 可选): 数据库名称 (默认: 当前数据库)
schema (string, 可选): 模式名称 (默认: 所有模式)

示例:

{
  "name": "list_tables",
  "arguments": {
    "database": "main",
    "schema": "main"
  }
}

{
  "success": true,
  "database": "main",
  "schema": "main",
  "tables": [
    {
      "schema": "main",
      "name": "users",
      "type": "table",
      "comment": "User accounts"
    },
    {
      "schema": "main",
      "name": "active_users",
      "type": "view",
      "comment": null
    }
  ],
  "tableCount": 1,
  "viewCount": 1
}

`list_columns`

列出表或视图的所有列。

参数:

table (string, 必需): 表或视图名称
database (string, 可选): 数据库名称
schema (string, 可选): 模式名称

示例:

{
  "name": "list_columns",
  "arguments": {
    "table": "users",
    "database": "main"
  }
}

{
  "success": true,
  "database": "main",
  "schema": "main",
  "table": "users",
  "objectType": "table",
  "columns": [
    {
      "name": "id",
      "type": "BIGINT",
      "nullable": false,
      "comment": null
    },
    {
      "name": "name",
      "type": "VARCHAR",
      "nullable": true,
      "comment": "User name"
    }
  ],
  "columnCount": 2
}

`switch_database_connection`

切换到不同的数据库 (可选启用)。

参数:

path (string, 必需): 数据库路径
create_if_not_exists (boolean, 可选): 如果不存在则创建 (仅读写模式)

示例:

{
  "name": "switch_database_connection",
  "arguments": {
    "path": "/path/to/new/database.duckdb"
  }
}

{
  "success": true,
  "message": "Switched to database: /path/to/new/database.duckdb",
  "previousDatabase": ":memory:",
  "currentDatabase": "/path/to/new/database.duckdb",
  "readOnly": false
}

⚙️ 配置

Claude Desktop

Settings → Developer → Edit Config

{
  "mcpServers": {
    "DuckDB (内存)": {
      "command": "npx",
      "args": ["-y", "mcp-duckdb-local@latest", "--db-path", ":memory:", "--read-write"]
    }
  }
}

Windows 用戶: 建議全局安裝後使用 mcp-duckdb-local 命令替代 npx。

Claude Code

claude mcp add --scope user duckdb \
  --transport stdio \
  -- npx -y mcp-duckdb-local@latest --db-path :memory: --read-write

VS Code

Ctrl+Shift+P → Preferences: Open User Settings (JSON)

{
  "mcpServers": {
    "DuckDB": {
      "command": "npx",
      "args": ["-y", "mcp-duckdb-local@latest", "--db-path", "/path/to/db.duckdb"]
    }
  }
}

Cursor

Settings → MCP → Add new global MCP server

🧑 开发文档

详细的开发指南、构建命令、测试和代码规范已移至 DEVELOPMENT.md。

快速参考：

# 安装依赖
yarn install

# 开发模式
yarn dev

# 构建
yarn build

# 运行测试
yarn test

# 打包分发
yarn build:bundle

完整开发文档请查看 DEVELOPMENT.md。

🤝 贡献

我们欢迎贡献！请遵循以下步骤:

Fork 仓库
创建功能分支 (git checkout -b feature/amazing-feature)
提交更改 (git commit -m 'feat: add amazing feature')
推送到分支 (git push origin feature/amazing-feature)
提交 Pull Request

贡献者

📄 许可证

本项目采用 Apache-2.0 许可证。

🙏 致谢

DuckDB - 强大的嵌入式数据库
FastMCP - MCP 服务器框架
motherduckdb/mcp-server-motherduck - Python 实现的灵感来源

📞 支持

本文档由 DuckDB MCP Server 生成 🦆

This server cannot be installed

license - permissive license

quality - not tested

maintenance

How are these scores calculated?

Maintenance

–Maintainers

–Response time

–Release cycle

–Releases (12mo)

Commit activity

Resources

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly
Lightport: Open-Sourcing Glama's AI Gateway
By punkpeye on April 27, 2026.
OpenAI
open source

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/MMHK/duckdb-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

DuckDB MCP Server

📖 目录

📝 简介

🆕 新版本更新

✨ 特点

🚀 快速开始

前置要求

安装

在内存模式下运行 (开发模式)

連接到本地 DuckDB 文件 (只讀模式)

連接到 MotherDuck (读写模式)

⚠️ Windows 用戶特別說明

方案 1：全局安裝（推薦）

方案 2：使用 npx 時添加 -y 標誌

方案 3：使用 yarn dlx

📦 安装

全局安装

本地安装

📖 使用方法

CLI 命令

命令行参数

环境变量

🔧 工具

execute_query

list_databases

list_tables

list_columns

switch_database_connection

⚙️ 配置

Claude Desktop

Claude Code

VS Code

Cursor

🧑 开发文档

🤝 贡献

贡献者

📄 许可证

🙏 致谢

📞 支持

Maintenance

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API

方案 2：使用 npx 時添加 `-y` 標誌

`execute_query`

`list_databases`

`list_tables`

`list_columns`

`switch_database_connection`