内容
# 思特斯 MCP 服务器（thoughtspot-mcp）
MCP服务器，用于[思特斯 REST API v2.0](https://developers.thoughtspot.com/docs/rest-apiv2-reference)。使用[官方MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)（FastMCP）构建。
允许任何与MCP兼容的客户端（Cursor、Claude Desktop、Claude Code、MCP Inspector等）通过自然语言与您的思特斯实例交互。
## 功能
- 18种工具，涵盖健康检查、元数据搜索/删除、TML导出/导入、数据仓库连接、数据检索和报告导出
- 核心资源的读取和写入操作（创建、更新、删除）
- TML往返：导出对象为思特斯建模语言，并重新导入（同步+异步，状态轮询）
- 数据访问：运行TML搜索查询并拉取Liveboard/Answer数据
- 以PDF、PNG、CSV和XLSX格式导出报告
- 自动的 bearer-token 交换，内存缓存，激进刷新（300秒有效期）和透明的401重试
- 摘要工具的Markdown和JSON响应格式
- 通过 **stdio** （本地）运行 — 与Cursor、Claude Desktop、Claude Code和Docker一起工作
- 与自托管思特斯和思特斯云一起工作
## 可用工具
| 工具 | 描述 |
|---|---|
| **健康检查** | |
| `thoughtspot_health_check` | 检查实例是否可达且凭证有效 |
| **元数据** | |
| `thoughtspot_search_metadata` | 搜索元数据对象（Liveboards、Answers、Models、Connections、Tags、Users...） |
| `thoughtspot_delete_metadata` | 永久删除一个或多个元数据对象 |
| **TML** | |
| `thoughtspot_export_tml` | 将思特斯对象导出为TML（思特斯建模语言） |
| `thoughtspot_import_tml` | 从TML定义导入（创建或更新）思特斯对象 |
| `thoughtspot_async_import_tml` | 启动异步TML导入并返回任务ID以轮询 |
| `thoughtspot_get_tml_import_status` | 轮询异步TML导入任务的状态 |
| **连接** | |
| `thoughtspot_search_connections` | 列出或过滤思特斯中配置的数据仓库连接 |
| `thoughtspot_get_connection` | 获取一个连接的完整详细信息（配置+注册对象）通过GUID或名称 |
| `thoughtspot_create_connection` | 创建新的数据仓库连接 |
| `thoughtspot_update_connection` | 更新连接 — 重命名、重新描述或注册表/模式 |
| `thoughtspot_set_connection_status` | 激活或停用连接 |
| `thoughtspot_delete_connection` | 永久删除连接 |
| **数据** | |
| `thoughtspot_search_data` | 对Worksheet、View、Table或SQL视图运行TML搜索查询 |
| `thoughtspot_get_liveboard_data` | 获取Liveboard可视化的数据 |
| `thoughtspot_get_answer_data` | 获取保存的Answer的数据 |
| **报告** | |
| `thoughtspot_export_liveboard_report` | 将Liveboard（及其可视化）导出为PDF、PNG、CSV或XLSX文件 |
| `thoughtspot_export_answer_report` | 将Answer导出为CSV、PDF、XLSX或PNG文件 |
## 先决条件
- 运行的**思特斯**实例，具备**REST API v2.0**访问权限 — 既可以是：
- 自托管思特斯，或
- [思特斯云](https://www.thoughtspot.com/)
- 具有服务账户用户，并具备您计划调用的工具所需的权限。
- 以下任意一项来运行服务器：
- **[uvx](https://docs.astral.sh/uv/)** （零安装；按需运行发布的包 — 参见[使用uvx运行](#使用uvx运行（零安装）)），或
- **[uv](https://docs.astral.sh/uv/)** + **Python 3.13+** （本地克隆/开发），或
- **[Docker](https://docs.docker.com/get-docker/)** （主机上不需要Python/uv）
## 快速入门
### 1. 克隆和安装
```bash
git clone https://github.com/trustxai/thoughtspot-mcp.git
cd thoughtspot-mcp
uv sync
```
### 2. 配置凭证
```bash
cp .env.example .env
```
使用您的`THOUGHTSPOT_HOST`、`THOUGHTSPOT_USERNAME`和`THOUGHTSPOT_SECRET_KEY`（受信任身份验证）或`THOUGHTSPOT_PASSWORD`编辑`.env`文件。有关详细信息，请参见[身份验证](#身份验证)。
### 3. 运行服务器
```bash
uv run thoughtspot-mcp
```
## 使用uvx运行（零安装）
[uvx](https://docs.astral.sh/uv/) 按需运行已发布的PyPI包 — 无需克隆，无需虚拟环境，无需持久安装。命令与包名匹配，因此不需要 `--from`：
```bash
uvx thoughtspot-mcp
```
凭证通过客户端的`env`块传递（如下所示），或在手动运行的shell中导出：
```bash
THOUGHTSPOT_HOST=https://my-instance.thoughtspot.cloud \
THOUGHTSPOT_USERNAME=<服务账户> \
THOUGHTSPOT_SECRET_KEY=<您的密钥> \
uvx thoughtspot-mcp
```
> **Python版本：** 包针对 **Python 3.13+**。uv自动提供匹配的解释器，因此这通常可以直接工作。如果您的环境固定了较旧的默认版本，请强制使用`uvx --python=3.13 thoughtspot-mcp`。
## 客户端配置
每个MCP客户端（Cursor、Claude Desktop等）都可以通过以下三种方式之一运行服务器：
- **uvx** — 零安装；按需运行发布的包（参见[使用uvx运行](#使用uvx运行（零安装）)）。
- **uv** — 从本地克隆；最适合开发。
- **Docker** — 主机上不需要Python/uv；所有内容都在容器中运行。构建一次镜像，每个客户端配置重用它。
### 构建Docker镜像（一次性）
```bash
docker build -t thoughtspot-mcp:latest .
```
### Cursor
添加到 `.cursor/mcp.json`（项目级）或 `~/.cursor/mcp.json`（全局）：
**选项A — uvx**
```json
{
"mcpServers": {
"thoughtspot": {
"command": "uvx",
"args": ["thoughtspot-mcp"],
"env": {
"THOUGHTSPOT_HOST": "https://my-instance.thoughtspot.cloud",
"THOUGHTSPOT_USERNAME": "<服务账户>",
"THOUGHTSPOT_SECRET_KEY": "<您的密钥>"
}
}
}
}
```
**选项B — uv**
```json
{
"mcpServers": {
"thoughtspot": {
"command": "uv",
"args": ["--directory", "/path/to/thoughtspot-mcp", "run", "thoughtspot-mcp"],
"env": {
"THOUGHTSPOT_HOST": "https://my-instance.thoughtspot.cloud",
"THOUGHTSPOT_USERNAME": "<服务账户>",
"THOUGHTSPOT_SECRET_KEY": "<您的密钥>"
}
}
}
}
```
**选项C — Docker**
```json
{
"mcpServers": {
"thoughtspot": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"--name", "thoughtspot-mcp",
"-e", "THOUGHTSPOT_HOST",
"-e", "THOUGHTSPOT_USERNAME",
"-e", "THOUGHTSPOT_SECRET_KEY",
"thoughtspot-mcp:latest"
],
"env": {
"THOUGHTSPOT_HOST": "https://my-instance.thoughtspot.cloud",
"THOUGHTSPOT_USERNAME": "<服务账户>",
"THOUGHTSPOT_SECRET_KEY": "<您的密钥>"
}
}
}
}
```
### Claude Desktop
添加到 `claude_desktop_config.json`：
**选项A — uv**
```json
{
"mcpServers": {
"thoughtspot": {
"command": "uv",
"args": ["--directory", "/path/to/thoughtspot-mcp", "run", "thoughtspot-mcp"],
"env": {
"THOUGHTSPOT_HOST": "https://my-instance.thoughtspot.cloud",
"THOUGHTSPOT_USERNAME": "<服务账户>",
"THOUGHTSPOT_SECRET_KEY": "<您的密钥>"
}
}
}
}
```
**选项B — Docker**
```json
{
"mcpServers": {
"thoughtspot": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"--name", "thoughtspot-mcp",
"-e", "THOUGHTSPOT_HOST",
"-e", "THOUGHTSPOT_USERNAME",
"-e", "THOUGHTSPOT_SECRET_KEY",
"thoughtspot-mcp:latest"
],
"env": {
"THOUGHTSPOT_HOST": "https://my-instance.thoughtspot.cloud",
"THOUGHTSPOT_USERNAME": "<服务账户>",
"THOUGHTSPOT_SECRET_KEY": "<您的密钥>"
}
}
}
}
```
### Claude Code
```bash
claude mcp add \
--env THOUGHTSPOT_HOST=https://my-instance.thoughtspot.cloud \
--env THOUGHTSPOT_USERNAME=<服务账户> \
--env THOUGHTSPOT_SECRET_KEY=<您的密钥> \
--transport stdio \
thoughtspot \
-- uvx thoughtspot-mcp
```
> `--` 将 `claude mcp add` 的自身标志与服务器命令分开。在 `--` 之前放置所有 `--env` 标志 **之前**，在 `--` 之后将任何内容传递给启动的进程。 将 `--env` 放在 `--` 之后会导致CLI误解析为 `uvx` 的参数。
### MCP Inspector
Inspector可以直接启动stdio服务器：
```bash
npx @modelcontextprotocol/inspector uvx thoughtspot-mcp
```
在Inspector的环境面板中设置`THOUGHTSPOT_HOST`、`THOUGHTSPOT_USERNAME`和您的凭证环境变量（或在shell中导出它们）。
## 身份验证
服务器通过交换凭证为**bearer token**，通过 `POST /api/rest/2.0/auth/token/full` 与思特斯REST API v2.0进行身份验证。令牌缓存在内存中，并作为 `Authorization: Bearer <token>` 附加在每个请求上。
凭证按**优先级**解析 — 可用的第一个选项获胜：
1. **`THOUGHTSPOT_ACCESS_TOKEN`** — 预取的bearer令牌。完全跳过令牌交换；当您已经拥有有效的令牌时使用它。
2. **`THOUGHTSPOT_SECRET_KEY`**（+ `THOUGHTSPOT_USERNAME`）— **受信任身份验证**。首选：不存储密码，并启用RLS模拟。在思特斯的**Develop → Security Settings**下启用它。
3. **`THOUGHTSPOT_PASSWORD`**（+ `THOUGHTSPOT_USERNAME`）— 用户名/密码令牌交换。最简单的是当受信任身份验证关闭时。
> **令牌有效期 + 自动刷新。** 思特斯访问令牌默认为 **300秒** 有效期。客户端积极刷新（有安全裕度），并在HTTP 401上透明地重试 **一次**，因此长时间运行的会话继续有效，无需手动重新身份验证。
### 环境变量
| 变量 | 必需 | 默认值 | 描述 |
|---|---|---|---|
| `THOUGHTSPOT_HOST` | 是 | — | 实例基本URL，例如 `https://my-instance.thoughtspot.cloud` （无 `/api/rest` 路径） |
| `THOUGHTSPOT_USERNAME` | 是\* | — | 用于令牌交换的服务账户用户名 |
| `THOUGHTSPOT_SECRET_KEY` | 是\* | — | 受信任身份验证的密钥（首选凭证） |
| `THOUGHTSPOT_PASSWORD` | 是\* | — | 密码（备用凭证） |
| `THOUGHTSPOT_ACCESS_TOKEN` | 否 | — | 预取的bearer令牌（跳过交换） |
| `THOUGHTSPOT_ORG_ID` | 否 | — | 目标特定Org（多租户实例） |
| `THOUGHTSPOT_TOKEN_VALIDITY_SECONDS` | 否 | `300` | 令牌交换时请求的令牌有效期 |
| `THOUGHTSPOT_REQUEST_TIMEOUT_SECONDS` | 否 | `30` | HTTP请求超时（秒） |
\* 提供 **一个** 凭证路径：`THOUGHTSPOT_ACCESS_TOKEN`，或 `THOUGHTSPOT_USERNAME` + `THOUGHTSPOT_SECRET_KEY`，或 `THOUGHTSPOT_USERNAME` + `THOUGHTSPOT_PASSWORD`。
## 手动运行（无需客户端）
如果您只想从CLI操作服务器：
```bash
# uvx — 无克隆
uvx thoughtspot-mcp
# uv
uv run thoughtspot-mcp
# Docker
docker run --rm -i --env-file .env thoughtspot-mcp:latest
```
## 故障排除
这些是真正的思特斯REST API v2.0需要注意的事项：
- **连接更新使用复数路径。** 通过 `connections/{id}/update` （复数 `connections`）更新连接。单数 `connection/{id}/update` 路径已**弃用** — 使用它可能会静默地无操作或返回错误。
- **连接配置必须包装。** 创建或更新连接时，数据仓库配置负载必须嵌套在 `data_warehouse_config` 键下。裸配置被拒绝。
- **全局速率限制 → HTTP 429。** 思特斯强制执行每秒 **100个请求/秒** 的全局速率限制。突发工具循环可能会触发它并收到 `HTTP 429 Too Many Requests`；请退后并重试。
- **相关问题需要尾部斜杠。** `/ai/relevant-questions/` 端点需要 **尾部斜杠**。省略它会导致路由失败（例如404/重定向），而不是预期响应。
## 贡献
欢迎贡献！打开一个问题或拉取请求以开始。
## 许可证
Apache-2.0 — 参见 [LICENSE](LICENSE) 以获取详细信息。
