RawTree MCP 服务器

一个面向 RawTree 的 MCP 服务器，RawTree 是一个用于非结构化数据的分析数据库。通过 SQL 查询数据、插入 JSON、检查表结构、查看 RawTree 日志，以及从 MCP 客户端（如 Claude Code、Cursor 和 Claude Desktop）管理数据库凭据。

功能特性

• 查询 — 对 RawTree 数据库执行只读 SQL 查询，并获取 JSON 行、元数据、统计信息和提示。

• 数据摄取 — 插入单个 JSON 对象、JSON 对象数组或公共 URL 数据。支持 RawTree 内置的转换功能，适用于 OTLP 轨迹/日志/指标、CloudWatch 日志、CloudTrail 和 Firehose。

• 表管理 — 列出表、查看表列和大小，以及在明确确认后删除表。

• 日志 — 通过结构化过滤器（类型、状态、来源、表名、提示、时间窗口和分页）查看 RawTree 的查询和插入历史记录。

• API 密钥 — 为数据库列出、创建和吊销 RawTree API 密钥。创建响应中包含一次性 API 密钥值。

• 组织 — 列出 OAuth 认证用户可访问的组织。

• 数据库 — 列出集群中的数据库，并验证对所选数据库的访问权限。

• 集群 — 列出专用集群，并在明确确认后配置集群。RawTree 强制执行用户和组织管理员授权。

• 传输方式 — 支持 stdio（用于本地 MCP 客户端）和双版本 Streamable HTTP（用于远程或多客户端部署），包括无状态 MCP 2026-07-28 请求和传统初始化握手客户端。

Related MCP server: Chakra MCP Server

设置

通过 RawTree CLI、仪表板或 API 创建 RawTree API 密钥。数据库 API 密钥以 rt_ 开头，足以用于数据工具，如 run-query、insert-json、list-tables 和 list-logs。

get_database 工具使用当前 API 密钥从 RawTree 的 keys 端点读取数据库身份标识，如果密钥是非管理员的只读数据库 API 密钥，则回退到 tables 端点。

使用方式

服务器支持两种传输模式：stdio（默认）和 HTTP。

Stdio 传输

快速设置

npx add-mcp @rawtree/mcp --name rawtree --env "RAWTREE_API_KEY=rt_xxxxxxxxx"

Claude Code

claude mcp add rawtree -e RAWTREE_API_KEY=rt_xxxxxxxxx -- npx -y @rawtree/mcp

Cursor

打开命令面板，选择 "Cursor 设置" > "MCP" > "添加新的全局 MCP 服务器"。

{
  "mcpServers": {
    "rawtree": {
      "command": "npx",
      "args": ["-y", "@rawtree/mcp"],
      "env": {
        "RAWTREE_API_KEY": "rt_xxxxxxxxx"
      }
    }
  }
}

Claude Desktop

打开 Claude Desktop 设置 > "开发者" 选项卡 > "编辑配置"。

{
  "mcpServers": {
    "rawtree": {
      "command": "npx",
      "args": ["-y", "@rawtree/mcp"],
      "env": {
        "RAWTREE_API_KEY": "rt_xxxxxxxxx"
      }
    }
  }
}

HTTP 传输

通过 HTTP 运行服务器，用于远程或基于 Web 的集成。在 HTTP 模式下，每个 MCP 客户端通过在 Authorization 头部传递其 RawTree API 密钥进行身份验证。

启动服务器：

npx -y @rawtree/mcp --http --port 3000

服务器监听在 http://127.0.0.1:3000，并通过 Streamable HTTP 在 /mcp 端点暴露 MCP 功能。

Claude Code

claude mcp add rawtree --transport http http://127.0.0.1:3000/mcp --header "Authorization: Bearer rt_xxxxxxxxx"

Cursor

{
  "mcpServers": {
    "rawtree": {
      "url": "http://127.0.0.1:3000/mcp",
      "headers": {
        "Authorization": "Bearer rt_xxxxxxxxx"
      }
    }
  }
}

你也可以通过 MCP_PORT 环境变量设置端口：

MCP_PORT=3000 npx -y @rawtree/mcp --http

选项

• --api-key：stdio 模式下的 RawTree 数据库 API 密钥

• --api-url：RawTree API 基础 URL，默认为 https://api.rawtree.com

• --database：用于限定路由的数据库名称

• --org：用于限定路由的组织名称

• --http：使用 HTTP 传输而非 stdio

• --port：使用 --http 时的 HTTP 端口，默认为 3000 或 MCP_PORT

环境变量：

• RAWTREE_API_KEY：RawTree 数据库 API 密钥

• RAWTREE_API_URL：RawTree API 基础 URL，默认为 https://api.rawtree.com

• RAWTREE_DATABASE：用于限定路由的数据库名称

• RAWTREE_ORG：用于限定路由的组织名称

• MCP_PORT：使用 --http 时的 HTTP 端口

工具

数据

• check-health — 检查 RawTree API 端点是否可访问。

• run-query — 执行只读 SQL 并返回 RawTree 的 JSON 查询响应。可接受组织、集群和数据库覆盖参数。

• insert-json — 向表中插入 JSON 对象，可选地使用 RawTree 转换功能。

• insert-from-url — 从公共 URL 获取数据并返回 RawTree 的 NDJSON 进度流。

表

• list-tables — 列出配置的数据库中的表。

• describe-table — 查看列、行数、字节数、数据库和组织信息。

• delete-table — 在明确确认后删除表。需要管理员权限。

日志

• list-logs — 读取 RawTree 的查询和插入日志。若未提供时间窗口，默认为最近一小时。

结构化日志过滤器包括：

{
  "statuses": ["error"],
  "types": ["insert"],
  "tables": ["events"],
  "origins": ["api"],
  "hints": "any",
  "limit": 50
}

API 密钥

• list-api-keys — 列出配置的数据库的 API 密钥。

• create-api-key — 创建具有 admin、read_write、write_only 或 read_only 权限的密钥。

• delete-api-key — 在明确确认后吊销密钥。

数据库

• list-databases — 列出组织与集群中的数据库。

• get_database — 验证选中的数据库并返回 { "name": "...", "organization": { "name": "..." } }。

组织

• list-organizations — 列出认证用户可访问的组织。需要用户凭据，例如 OAuth。

集群

• list-clusters — 列出组织内可访问的专用集群。

• create-cluster — 在明确确认组织及其可计费资源配置后，配置专用集群。

集群工具会向每个 MCP 客户端广播。RawTree API 仍然是授权边界：集群访问需要用户访问令牌，集群创建还需要组织管理员权限。

程序化托管部署可以在每个适用工具上要求显式资源选择。组织与集群标识资源边界；数据库仍然是可选覆盖，省略时默认为 default。这使得一个 OAuth 支持的 MCP 连接可以在不同组织、集群和数据库之间切换，而无需将上下文编码到 MCP URL 中：

const server = createMcpServer(client, { requireExplicitScope: true });

示例

查询

{
  "organization": "acme",
  "cluster": "production",
  "database": "analytics",
  "sql": "SELECT count() AS rows FROM events"
}

插入 JSON

{
  "table": "events",
  "data": [
    {
      "event": "signup",
      "user_id": "user_123",
      "source": "mcp"
    }
  ]
}

插入 OTLP 轨迹

{
  "table": "traces",
  "transform": "otlp-traces",
  "data": {
    "resource": {
      "attributes": [
        {
          "key": "service.name",
          "value": {
            "stringValue": "api"
          }
        }
      ]
    },
    "scopeSpans": [
      {
        "spans": [
          {
            "name": "GET /health",
            "spanId": "abc"
          }
        ]
      }
    ]
  }
}

调试失败的插入

{
  "statuses": ["error"],
  "types": ["insert"],
  "startTime": "2026-05-28T09:00:00.000Z",
  "endTime": "2026-05-28T10:00:00.000Z",
  "limit": 25
}

本地开发

1. 安装并构建：

pnpm install
pnpm build

2. 在 MCP 客户端中使用本地构建版本：

claude mcp add rawtree -e RAWTREE_API_KEY=rt_xxxxxxxxx -- node /absolute/path/to/rawtree-mcp/dist/index.js

使用 MCP 客户端进行实时测试

在观察模式下运行 TypeScript，然后将单独的 MCP 客户端指向构建后的服务器：

pnpm tsc --watch

{
  "mcpServers": {
    "rawtree-dev": {
      "command": "node",
      "args": ["/absolute/path/to/rawtree-mcp/dist/index.js"],
      "env": {
        "RAWTREE_API_KEY": "rt_xxxxxxxxx"
      }
    }
  }
}

每次重新构建后重启 MCP 客户端会话。

程序化使用

包根目录暴露了可复用的 MCP 服务器层。Node HTTP 传输可从 @rawtree/mcp/http 单独获取，因此托管适配器可以使用服务器工厂而无需导入本地进程入口点。

import { createMcpServer, RawTreeClient } from '@rawtree/mcp';

const client = new RawTreeClient({ apiKey: process.env.RAWTREE_API_KEY! });
const server = createMcpServer(client);

发布

发布由 GitHub Actions 的 Publish 工作流处理。

需要的仓库密钥：

• NPM_TOKEN：具有发布 @rawtree/mcp 权限的 npm 自动化令牌。

发布流程：

1. 更新 package.json 中的版本号。

2. 将更改推送到 main 分支。

3. 创建并发布一个与包版本匹配的标签（如 v0.2.0）的 GitHub Release。

工作流会验证发布标签与 package.json 中的版本一致，运行 lint、测试和构建，然后通过 npm provenance 发布：

npm publish --provenance --access public

使用 MCP Inspector 进行测试

首先构建：

pnpm build

启动 Inspector：

RAWTREE_API_KEY=rt_xxxxxxxxx pnpm inspector

在 Inspector UI 中，选择 stdio：

• 命令：node

• 参数：dist/index.js

• 环境变量：RAWTREE_API_KEY=rt_xxxxxxxxx

RawTree 参考资料

• RawTree 文档

• llms.txt

• OpenAPI 规范