SingleStore MCP Server

官方

与SingleStore数据库平台交互

GitHub
33

文档

SingleStore MCP 服务器

MIT Licence PyPI Downloads

[模型上下文协议]((https://modelcontextprotocol.io/introduction)（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 密钥，因为 OAuth 流程不支持在 Docker 容器中运行的服务器。

{
  "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。