MCP Server Duckdb

🚀 mcp-server-duckdb

這是一個為DuckDB實現的模型上下文協議（MCP）服務器，它提供了通過MCP工具進行數據庫交互的能力。DuckDB非常適合本地分析，藉助此服務器，用戶能夠更便捷地與DuckDB數據庫進行交互操作。

🚀 快速開始

本服務器通過模型上下文協議（MCP）與DuckDB數據庫進行交互，支持查詢、表創建和架構檢查等數據庫操作。你可以按照以下步驟快速使用該服務器：

安裝

通過以下命令安裝：

uvx add mcp-server-duckdb

在Claude Desktop上進行集成時，請將以下內容添加到~/.config/claude.yaml：

mcp:
  servers:
    - duckdb:
        class_path: mcp_server_duckdb.DuckDBMCPHandler

使用

在Claude Desktop上使用時，可以通過以下命令運行：

uvx serve --port 12345 duckdb:mcp-server-duckdb

然後在Claude Desktop中配置MCP端點為http://localhost:12345

調試

通過以下命令啟動調試服務器：

uvx debug duckdb:mcp-server-duckdb

該調試器提供以下功能：

• 請求/響應通信的可見性
• 工具執行的跟蹤
• 服務器狀態監控
• 錯誤消息顯示

✨ 主要特性

• 統一查詢接口：服務器提供一個統一的query函數，現代大語言模型（LLM）可以為任何數據庫操作生成適當的SQL語句（如SELECT、CREATE TABLE、JOIN等），而無需分別指定端點。
• 只讀模式保護：當服務器以只讀模式運行時，DuckDB的內置只讀保護將被啟用，語言模型（LLM）無法執行任何寫入操作（如CREATE、INSERT、UPDATE、DELETE），從而保持數據完整性並防止意外更改。

📦 安裝指南

必要參數

• db-path（字符串）：DuckDB數據庫文件的路徑
  • 服務器將自動創建數據庫文件及其父目錄，如果它們不存在
  • 如果指定--readonly且數據庫文件不存在，服務器將無法啟動並顯示錯誤

可選參數

• --readonly：以只讀模式運行服務器
  • 描述：當此標誌設置時，服務器將以只讀模式運行。這意味著：
    • DuckDB數據庫將以read_only=True打開，阻止任何寫入操作。
    • 如果指定的數據庫文件不存在，則不會創建它。
    • 安全性優勢：防止語言模型（LLM）執行任何寫入操作，確保數據安全
  • 參考：DuckDB文檔

💻 使用示例

基礎用法

該服務器實現了以下數據庫交互工具：

• query：在DuckDB數據庫上執行任意SQL查詢
  • 輸入：query（字符串）- 任何有效的DuckDB SQL語句
  • 輸出：查詢結果作為文本（或成功消息，用於CREATE/INSERT等操作）

# 以下是使用query工具的示例
# 假設已經正確配置並啟動了服務器
# 這裡只是示意代碼，實際使用時需要根據具體情況調整
import requests

# 假設MCP端點為http://localhost:12345
url = "http://localhost:12345"
query = "SELECT * FROM your_table"
data = {
    "query": query
}
response = requests.post(url, json=data)
print(response.text)

高級用法

在實際應用中，你可以結合大語言模型（LLM）來使用該服務器。例如，讓LLM根據需求生成SQL語句，然後通過query工具執行這些語句。

# 假設已經有一個可以生成SQL語句的LLM
# 這裡只是示意代碼，實際使用時需要根據具體情況調整
import requests
from your_llm_module import generate_sql

# 假設MCP端點為http://localhost:12345
url = "http://localhost:12345"
# 讓LLM生成SQL語句
sql = generate_sql("查詢所有用戶信息")
data = {
    "query": sql
}
response = requests.post(url, json=data)
print(response.text)

📚 詳細文檔

組件

資源

目前沒有實現任何自定義資源。

提示語

目前沒有實現任何自定義提示語。

注意事項

⚠️ 重要提示

該服務器提供一個統一的query函數，而不是單獨的專業化功能，因為現代大語言模型（LLM）可以為任何數據庫操作生成適當的SQL語句（如SELECT、CREATE TABLE、JOIN等），而無需分別指定端點。

⚠️ 重要提示

當服務器以只讀模式運行時，DuckDB的內置只讀保護將被啟用。 這意味著語言模型（LLM）無法執行任何寫入操作（如CREATE、INSERT、UPDATE、DELETE），從而保持數據完整性並防止意外更改。

📄 許可證

查看許可證信息請點擊：PyPI - 許可證