SingleStore MCP Server

官方

與 SingleStore 資料庫平台互動

GitHub
33

文件

SingleStore MCP 伺服器

MIT Licence PyPI Downloads

模型上下文協定 (MCP) 是一項標準化協定，旨在管理大型語言模型 (LLM) 與外部系統之間的上下文。此儲存庫提供 SingleStore 的安裝程式與 MCP 伺服器，實現無縫整合。

透過 MCP，您可以使用 Claude Desktop、Claude Code、Cursor 或任何相容的 MCP 用戶端，以自然語言與 SingleStore 互動，輕鬆執行複雜操作。

💡 專業提示：不確定 MCP 伺服器能做什麼？只需在聊天中呼叫 /help 提示詞即可！

需求

  • Python >= v3.10.0
  • 已在 Python 環境中安裝 uvx
  • VS Code、Cursor、Windsurf、Claude Desktop、Claude Code、Goose 或任何其他 MCP 用戶端

入門指南

入門指南

首先，在您的用戶端中安裝 SingleStore MCP 伺服器。

標準設定適用於大多數工具：

{
  "mcpServers": {
    "singlestore-mcp-server": {
      "command": "uvx",
      "args": [
        "singlestore-mcp-server",
        "start"
      ]
    }
  }
}

無需 API 金鑰、權杖或環境變數！ 伺服器啟動時會自動透過瀏覽器 OAuth 處理驗證。

Claude Desktop

自動設定：

uvx singlestore-mcp-server init --client=claude-desktop

手動設定： 請依照 MCP 安裝指南，使用上述標準設定。

Claude Code

自動設定：

uvx singlestore-mcp-server init --client=claude-code

這將自動為您執行 Claude CLI 指令。

手動設定：

claude mcp add singlestore-mcp-server uvx singlestore-mcp-server start
Cursor

自動設定：

uvx singlestore-mcp-server init --client=cursor

手動設定： 前往 Cursor Settings -> MCP -> Add new MCP Server。依喜好命名，使用 command 類型，指令為 uvx singlestore-mcp-server start。您也可以透過點擊 Edit 來驗證設定或新增命令列引數。

VS Code

自動設定：

uvx singlestore-mcp-server init --client=vscode

手動設定： 請依照 MCP 安裝指南，使用上述標準設定。您也可以使用 VS Code CLI 進行安裝：

code --add-mcp '{"name":"singlestore-mcp-server","command":"uvx","args":["singlestore-mcp-server","start"]}'

安裝完成後，SingleStore MCP 伺服器即可在 VS Code 中與您的 GitHub Copilot 代理程式搭配使用。

Windsurf

自動設定：

uvx singlestore-mcp-server init --client=windsurf

手動設定： 請依照 Windsurf MCP 文件。使用上述標準設定。

Gemini CLI

自動設定：

uvx singlestore-mcp-server init --client=gemini

手動設定： 請依照 MCP 安裝指南，使用上述標準設定。

LM Studio

自動設定：

uvx singlestore-mcp-server init --client=lm-studio

手動設定： 前往右側邊欄的 Program -> Install -> Edit mcp.json。使用上述標準設定。

Goose

僅限手動設定： 前往 Advanced settings -> Extensions -> Add custom extension。依喜好命名，使用類型 STDIO，並將 command 設為 uvx singlestore-mcp-server start。點擊「新增擴充功能」。

Qodo Gen

僅限手動設定： 在 VSCode 或 IntelliJ 中開啟 Qodo Gen 聊天面板 → 連接更多工具 → + 新增 MCP → 貼上上述標準設定。

點擊 儲存。

使用 Docker

注意： 使用 Docker 時需要 API 金鑰，因為在 Docker 容器中執行的伺服器不支援 OAuth 流程。

{
  "mcpServers": {
    "singlestore-mcp-server": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "--init", "--pull=always",
        "-e", "MCP_API_KEY=your_api_key_here",
        "singlestore/mcp-server-singlestore"
      ]
    }
  }
}

您可以自行建置 Docker 映像檔：

docker build -t singlestore/mcp-server-singlestore .

為了提升安全性，我們建議使用 Docker Desktop 來設定 SingleStore MCP 伺服器——詳情請參閱此部落格文章，了解 Docker 全新的 MCP 目錄。

元件

工具

伺服器實作了以下工具：

  • get_user_info：擷取目前使用者的詳細資訊

    • 無需引數
    • 回傳使用者資訊與詳細資料

  • organization_info：擷取使用者目前所屬組織的詳細資訊

    • 無需引數
    • 回傳組織的詳細資料

  • choose_organization：從可用組織中選擇（僅在未設定 API 金鑰環境變數時可用）

    • 無需引數
    • 回傳可供選擇的組織清單

  • set_organization：設定作用中的組織（僅在未設定 API 金鑰環境變數時可用）

    • 引數：organization_id (字串)
    • 將指定的組織設為作用中

  • workspace_groups_info：擷取使用者可存取的工作區群組詳細資訊

    • 無需引數
    • 回傳工作區群組的詳細資料

  • workspaces_info：擷取特定工作區群組中的工作區詳細資訊

    • 引數：workspace_group_id (字串)
    • 回傳工作區的詳細資料

  • resume_workspace：恢復已暫停的工作區

    • 引數：workspace_id (字串)
    • 恢復指定的工作區

  • list_starter_workspaces：列出使用者可存取的所有入門工作區

    • 無需引數
    • 回傳可用入門工作區的詳細資料

  • create_starter_workspace：建立新的入門工作區

    • 引數：工作區設定參數
    • 回傳已建立的入門工作區詳細資料

  • terminate_starter_workspace：終止現有的入門工作區

    • 引數：workspace_id (字串)
    • 終止指定的入門工作區

  • list_regions：擷取所有支援工作區的區域清單

    • 無需引數
    • 回傳可用區域清單

  • list_sharedtier_regions：擷取共享層級區域清單

    • 無需引數
    • 回傳共享層級區域清單

  • run_sql：在已連線的工作區上執行 SQL 操作

    • 引數：workspace_id、database、sql_query 以及連線參數
    • 以結構化格式回傳 SQL 查詢結果

  • create_notebook_file：在 SingleStore Spaces 中建立新的筆記本檔案

    • 引數：notebook_name、content (選用)
    • 回傳已建立的筆記本詳細資料

  • upload_notebook_file：上傳筆記本檔案至 SingleStore Spaces

    • 引數：file_path、notebook_name
    • 回傳已上傳的筆記本詳細資料

  • create_job_from_notebook：從筆記本建立排程工作

    • 引數：工作設定，包含 notebook_path、schedule_mode 等
    • 回傳已建立的工作詳細資料

  • get_job：擷取現有工作的詳細資訊

    • 引數：job_id (字串)
    • 回傳指定工作的詳細資料

  • delete_job：刪除現有工作

    • 引數：job_id (字串)
    • 刪除指定的工作

  • stage_list_files：列出 Stage 部署檔案系統中的檔案與資料夾

    • 引數：deployment_id (字串)、path (字串，選用)
    • 回傳資料夾內容，包含檔案與子資料夾

  • stage_get_file：依路徑從 Stage 取得檔案

    • 引數：deployment_id (字串)、path (字串)、return_type (字串：'metadata'、'url' 或 'content')
    • 回傳檔案中繼資料、下載 URL 或文字內容

  • stage_create_folder：在 Stage 中建立資料夾

    • 引數：deployment_id (字串)、path (字串)
    • 回傳建立狀態

  • stage_upload_file：上傳包含文字內容的檔案至 Stage

    • 引數：deployment_id (字串)、path (字串)、content (字串)、local_path (字串)
    • 回傳上傳狀態

  • stage_move：移動或重新命名 Stage 中的檔案或資料夾

    • 引數：deployment_id (字串)、source_path (字串)、destination_path (字串)
    • 回傳移動狀態

  • stage_delete：從 Stage 刪除檔案或資料夾

    • 引數：deployment_id (字串)、path (字串)
    • 回傳刪除狀態

注意：組織管理工具（choose_organization 和 set_organization）僅在未設定 API 金鑰環境變數時可用，以便在 OAuth 驗證期間進行互動式組織選擇。

開發

先決條件

  • Python >= 3.11
  • 用於依賴項管理的 uv

設定

  1. 複製儲存庫：
git clone https://github.com/singlestore-labs/mcp-server-singlestore.git
cd mcp-server-singlestore
  1. 安裝依賴項：
uv sync --dev
  1. 設定預提交掛鉤（選用但建議）：
uv run pre-commit install

開發工作流程

# Quick quality checks (fast feedback)
./scripts/check.sh

# Run tests independently
./scripts/test.sh

# Comprehensive validation (before PRs)
./scripts/check-all.sh

# Create and publish releases
./scripts/release.sh

執行測試

# Run test suite with coverage
./scripts/test.sh

# Or use pytest directly
uv run pytest
uv run pytest --cov=src --cov-report=html

程式碼品質

我們使用 Ruff 進行程式碼檢查與格式化：

# Format code
uv run ruff format src/ tests/

# Lint code
uv run ruff check src/ tests/

# Lint and fix issues automatically
uv run ruff check --fix src/ tests/

發布流程

發布透過 git 標籤與自動化 PyPI 發布進行管理：

  1. 建立發布：./scripts/release.sh（互動式工具）
  2. 自動發布：由推送版本標籤觸發
  3. 無需手動上傳至 PyPI - 全自動化管線

請參閱 scripts/dev-workflow.md 以取得詳細的工作流程文件。