AI导哈

数据查询服务器

一个通过DuckDB集成使LLM能够使用SQL查询数据集的数据查询服务器。

  • by cboettig
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 cboettig/mcp-server

使用说明

数据查询服务器-MCP

MCP（模型上下文协议）服务器，使LLM能够通过DuckDB集成使用SQL查询数据集。

特性

  • SQL查询执行：对预加载的数据集执行SQL查询
  • 架构检查：探索表结构和元数据
  • 示例数据集：包括用于演示的销售和客户数据
  • Docker支持：使用Docker和Docker compose轻松部署
  • 类型安全：提高代码质量的完整类型提示

快速开始

1.安装依赖项

uv sync --dev --all-extras

2.运行服务器

uv run python -m data_query_server

3.使用Docker

# Build and run with docker-compose
docker-compose up --build

# Or build manually
docker build -t data-query-server .
docker run -v ./data:/app/data data-query-server

使用预构建图像

Docker镜像在每次发布时都会自动构建并发布到GitHub容器注册表：

# Pull the latest image
docker pull ghcr.io/cboettig/mcp-server:latest

# Run with the pre-built image
docker run --rm ghcr.io/cboettig/mcp-server:latest

# Or use with docker-compose by updating the image reference
# image: ghcr.io/cboettig/mcp-server:latest

可用标签：

  • latest：主分支的最新稳定版本
  • v1.0.0：特定版本标签
  • main：主分行最新消息

可用工具

MCP服务器为LLM提供以下工具：

  • sql_query：对数据集执行SQL查询
  • describe_table：获取特定表的架构和元数据
  • list_tables：列出所有可用的表格及其说明

示例数据集

服务器附带了两个预加载的数据集：

销售表

  • order_id：唯一订单标识符
  • customer_id：客户参考
  • product：产品名称（产品A、B、C）
  • quantity：订购的物品数量
  • price：每件商品的价格
  • order_date：订单日期

客户表

  • customer_id：唯一客户标识符
  • name：客户名称
  • email：客户电子邮件地址
  • city：客户所在城市
  • registration_date：客户注册日期

查询示例

-- Top selling products
SELECT product, SUM(quantity * price) as revenue 
FROM sales 
GROUP BY product 
ORDER BY revenue DESC;

-- Customer order history
SELECT c.name, COUNT(s.order_id) as order_count, SUM(s.quantity * s.price) as total_spent
FROM customers c
JOIN sales s ON c.customer_id = s.customer_id
GROUP BY c.customer_id, c.name
ORDER BY total_spent DESC;

-- Monthly sales trends
SELECT 
    strftime('%Y-%m', order_date) as month,
    COUNT(*) as orders,
    SUM(quantity * price) as revenue
FROM sales 
GROUP BY strftime('%Y-%m', order_date)
ORDER BY month;

发展

项目结构

src/
├── data_query_server/
│   ├── __init__.py
│   ├── __main__.py
│   └── server.py          # Main MCP server implementation
data/                       # DuckDB database files
datasets/                   # Additional dataset files
.vscode/
├── mcp.json               # MCP server configuration
└── tasks.json             # VS Code tasks

配置

MCP服务器配置在 .vscode/mcp.json:

{
  "servers": {
    "data-query-server": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "python", "-m", "data_query_server"]
    }
  }
}

添加新数据集

要向服务器添加新数据集，请执行以下操作：

  1. 将CSV文件放入 datasets/ 目录
  2. 修改 load_sample_datasets() 方法in server.py
  3. 更新 available_datasets 元数据

例子：

# Load your CSV data
new_data = pd.read_csv('datasets/your_data.csv')

# Create table in DuckDB
self.conn.execute("CREATE OR REPLACE TABLE your_table AS SELECT * FROM new_data")

# Add metadata
self.available_datasets['your_table'] = {
    'description': 'Description of your dataset',
    'columns': list(new_data.columns),
    'row_count': len(new_data)
}

贡献

  1. 分叉存储库
  2. 创建要素分支
  3. 进行更改
  4. 添加测试
  5. 提交拉取请求

许可证

MIT许可证

  • 每个笔记资源都有一个名称、描述和文本/纯MIME类型

鼓励

服务器提供一个提示：

  • 总结笔记：创建所有存储笔记的摘要
    • 可选的“style”参数，用于控制详细程度（简短/详细）
    • 生成将所有当前注释与样式首选项组合的提示

工具

服务器实现了一个工具：

  • 添加注释：向服务器添加新注释
    • 将“name”和“content”作为必需的字符串参数
    • 更新服务器状态并通知客户端资源更改

配置

[TODO:添加特定于您的实现的配置详细信息]

快速启动

安装

克劳德桌面

在MacOS上： ~/Library/Application\ Support/Claude/claude_desktop_config.json 在Windows上： %APPDATA%/Claude/claude_desktop_config.json

Development/Unpublished Servers Configuration ``` "mcpServers": { "data-query-server": { "command": "uv", "args": [ "--directory", "/home/cboettig/Documents/github/schmidtdse/mcp-server", "run", "data-query-server" ] } } ```
Published Servers Configuration ``` "mcpServers": { "data-query-server": { "command": "uvx", "args": [ "data-query-server" ] } } ```

发展

建筑与出版

准备分发包裹：

  1. 同步依赖关系并更新锁文件：
uv sync
  1. 构建包分发：
uv build

这将在 dist/ 目录。

  1. 发布到PyPI：
uv publish

注意：您需要通过环境变量或命令标志设置PyPI凭据：

  • 令牌： --token 或 UV_PUBLISH_TOKEN
  • 或用户名/密码： --username/UV_PUBLISH_USERNAME 和 --password/UV_PUBLISH_PASSWORD

调试

由于MCP服务器在stdio上运行，调试可能具有挑战性。为了达到最佳调试效果 经验，我们强烈建议使用 MCP检查员.

您可以通过以下方式启动MCP检查器 npm 使用此命令：

npx @modelcontextprotocol/inspector uv --directory /home/cboettig/Documents/github/schmidtdse/mcp-server run data-query-server

启动后，检查器将显示一个URL，您可以在浏览器中访问该URL以开始调试。

相关 MCP