SingleStore MCP Server

SingleStore MCP 服务

模型上下文协议（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 处理身份验证。

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

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

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

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

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

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

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

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

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

**注意：**使用 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 Catalog 的详情，请参阅这篇博客文章。

组件

工具

该服务实现了以下工具：

• 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（string）、path（string）
  • 返回创建状态

• stage_upload_file：将包含文本内容的文件上传到 Stage

  • 参数：deployment_id（string）、path（string）、content（string）、local_path（string）
  • 返回上传状态

• stage_move：在 Stage 中移动或重命名文件或文件夹

  • 参数：deployment_id（string）、source_path（string）、destination_path（string）
  • 返回移动状态

• stage_delete：从 Stage 中删除文件或文件夹

  • 参数：deployment_id（string）、path（string）
  • 返回删除状态

注意：仅当未设置 API 密钥环境变量时，才可使用组织管理工具（choose_organization 和 set_organization），以便在 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. 设置 pre-commit 钩子（可选，但建议设置）：

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。