RawTree MCP 서버

RawTree를 위한 MCP 서버입니다. RawTree는 비정형 데이터를 위한 분석 데이터베이스입니다. SQL로 데이터를 쿼리하고, JSON을 삽입하며, 테이블 스키마를 검사하고, RawTree 로그를 확인하며, Claude Code, Cursor, Claude Desktop과 같은 MCP 클라이언트에서 데이터베이스 자격 증명을 관리할 수 있습니다.

기능

• 쿼리 — RawTree 데이터베이스에 대해 읽기 전용 SQL을 실행하고 JSON 행, 메타데이터, 통계, 힌트를 반환합니다.

• 수집 — 단일 JSON 객체, JSON 객체 배열 또는 공개 URL 데이터를 삽입합니다. OTLP 트레이스/로그/메트릭, CloudWatch Logs, CloudTrail, Firehose를 위한 RawTree 내장 변환을 지원합니다.

• 테이블 — 테이블 목록을 조회하고, 테이블 열과 크기를 설명하며, 명시적 확인 후 테이블을 삭제합니다.

• 로그 — 유형, 상태, 출처, 테이블, 힌트, 시간 범위, 페이지네이션에 대한 구조화된 필터로 RawTree 쿼리 및 삽입 기록을 검사합니다.

• API 키 — 데이터베이스에 대한 RawTree API 키를 조회, 생성, 취소합니다. 생성 응답에는 일회성 API 키 값이 포함됩니다.

• 조직 — OAuth 인증 사용자가 사용할 수 있는 조직을 조회합니다.

• 데이터베이스 — 클러스터 내 데이터베이스 목록을 조회하고 선택한 데이터베이스에 대한 접근을 확인합니다.

• 클러스터 — 전용 클러스터 목록을 조회하고 명시적 확인 후 클러스터를 프로비저닝합니다. RawTree는 사용자 및 조직 관리자 권한을 적용합니다.

• 전송 방식 — 로컬 MCP 클라이언트를 위한 stdio와 원격 또는 다중 클라이언트 배포를 위한 이중 시대 Streamable HTTP를 지원합니다. 여기에는 상태 비저장 MCP 2026-07-28 요청과 레거시 initialize 핸드셰이크 클라이언트가 포함됩니다.

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의 키 엔드포인트에서 데이터베이스 ID를 읽습니다. 관리자가 아닌 읽기 가능 데이터베이스 API 키의 경우 테이블 엔드포인트가 대체됩니다.

사용법

서버는 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 Settings" > "MCP" > "Add new global MCP server"를 선택하세요.

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

Claude Desktop

Claude Desktop 설정 > "Developer" 탭 > "Edit Config"를 여세요.

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

HTTP 전송

원격 또는 웹 기반 통합을 위해 HTTP로 서버를 실행하세요. 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: stdio 대신 HTTP 전송 사용

• --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 쿼리 및 삽입 로그를 읽습니다. 시간 범위가 제공되지 않으면 기본적으로 지난 1시간으로 설정됩니다.

구조화된 로그 필터는 다음과 같습니다:

{
  "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 릴리스를 생성하고 게시합니다.

워크플로우는 릴리스 태그가 package.json과 일치하는지 확인하고, 린트, 테스트, 빌드를 실행한 후 npm 증명과 함께 게시합니다:

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 스펙