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 生成 🦆