DuckDB MCP Server

已改名为 mcp-duckdb-local

📖 目录

• 简介
• 特点
• 快速开始
• 安装
• 使用方法
• 工具
• 配置
• 客户端集成
• 贡献
• 许可证
• 开发文档

---

📝 简介

这是一个本地运行的 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。

---

🤝 贡献

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

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

贡献者

• tdoehmen
• krish-adi
• leonardovida
• mslosarek
• mehd-io
• MMHK

---

📄 许可证

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

---

🙏 致谢

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

---

📞 支持

• GitHub Issues
• MCP Discord
• MotherDuck MCP Docs

---

本文档由 DuckDB MCP Server 生成 🦆