# DuckDB MCP Server

[![npm version](https://img.shields.io/npm/v/mcp-duckdb-local.svg)](https://www.npmjs.com/package/mcp-duckdb-local)
[![npm downloads](https://img.shields.io/npm/dm/mcp-duckdb-local.svg)](https://www.npmjs.com/package/mcp-duckdb-local)
[![npm license](https://img.shields.io/npm/l/mcp-duckdb-local.svg)](https://www.npmjs.com/package/mcp-duckdb-local)
[![GitHub stars](https://img.shields.io/github/stars/MMHK/duckdb-mcp)](https://github.com/MMHK/duckdb-mcp)
[![npm total downloads](https://img.shields.io/npm/dt/mcp-duckdb-local.svg)](https://www.npmjs.com/package/mcp-duckdb-local)

**已改名为 `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

### 安装

```bash
# 使用 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
```

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

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

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

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

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

### 連接到 MotherDuck (读写模式)

```json
{
  "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：全局安裝（推薦）

```bash
npm install -g mcp-duckdb-local
```

然後在 MCP 配置中使用：

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

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

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

### 方案 3：使用 yarn dlx

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

---

## 📦 安装

### 全局安装

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

### 本地安装

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

---

## 📖 使用方法

### CLI 命令

```bash
# 显示帮助
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 查询

**示例**:

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

**返回**:

```json
{
  "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`

列出所有可用数据库。

**参数**: 无

**示例**:

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

**返回**:

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

---

### `list_tables`

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

**参数**:

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

**示例**:

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

**返回**:

```json
{
  "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, 可选): 模式名称

**示例**:

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

**返回**:

```json
{
  "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, 可选): 如果不存在则创建 (仅读写模式)

**示例**:

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

**返回**:

```json
{
  "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`

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

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

### Claude Code

```bash
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)`

```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](DEVELOPMENT.md)。

快速参考：

```bash
# 安装依赖
yarn install

# 开发模式
yarn dev

# 构建
yarn build

# 运行测试
yarn test

# 打包分发
yarn build:bundle
```

完整开发文档请查看 [DEVELOPMENT.md](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](https://github.com/tdoehmen)
- [krish-adi](https://github.com/krish-adi)
- [leonardovida](https://github.com/leonardovida)
- [mslosarek](https://github.com/mslosarek)
- [mehd-io](https://github.com/mehd-io)
- [MMHK](https://github.com/MMHK)

---

## 📄 许可证

本项目采用 [Apache-2.0 许可证](LICENSE)。

---

## 🙏 致谢

- [DuckDB](https://duckdb.org) - 强大的嵌入式数据库
- [FastMCP](https://github.com/jarParams/fastmcp) - MCP 服务器框架
- [motherduckdb/mcp-server-motherduck](https://github.com/motherduckdb/mcp-server-motherduck) - Python 实现的灵感来源

---

## 📞 支持

- [GitHub Issues](https://github.com/MMHK/duckdb-mcp/issues)
- [MCP Discord](https://discord.gg/modelcontextprotocol)
- [MotherDuck MCP Docs](https://motherduck.com/docs/sql-reference/mcp/)

---

_本文档由 DuckDB MCP Server 生成 🦆_