> ## Documentation Index
> Fetch the complete documentation index at: https://www.helius.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Helius MCP 서버

> Helius용 MCP 서버 — AI 도우미에게 Solana 쿼리, 트랜잭션 전송, 웹훅, 스트리밍, 지갑 분석 및 자동 계정 가입을 완벽하게 액세스할 수 있는 10개의 라우팅 도구 제공.

[Helius MCP 서버](https://www.npmjs.com/package/helius-mcp)는 AI 도구가 **10개의 공용 도구**를 통해 Helius API에 직접 액세스할 수 있도록 합니다. — 모든 Helius 및 Solana 기능을 다루는 9개의 라우팅 도메인 도구와 대량 응답 페이징을 위한 `expandResult` 포함.

<CardGroup cols={2}>
  <Card title="9 라우팅 도구" icon="bolt">
    도메인 그룹화 도구(`heliusWallet`, `heliusAsset`, `heliusTransaction`, …) — 모든 Helius 작업은 이들 중 하나를 통해 도달 가능합니다.
  </Card>

  <Card title="계정 가입" icon="robot">
    AI 도구에서 Helius 계정 생성 — 호스팅 링크를 통해 결제하거나 로컬 키페어에서 USDC 자동 결제
  </Card>

  <Card title="실시간 데이터" icon="signal-stream">
    AI 도구에서 직접 향상된 WebSockets 및 LaserStream gRPC 구독
  </Card>

  <Card title="어떤 MCP 클라이언트든" icon="plug">
    Claude Code, Claude Desktop, Cursor, VS Code, Windsurf, Codex 및 모든 MCP 호환 도구와 작동
  </Card>
</CardGroup>

## MCP란 무엇인가요?

[모델 컨텍스트 프로토콜(MCP)](https://modelcontextprotocol.io/)은 Anthropic이 도입한 오픈소스 표준으로, AI 모델이 외부 데이터 소스, 도구 및 API에 안전하게 연결할 수 있도록 합니다. 이 프로토콜은 클라이언트-서버 아키텍처를 사용하여, 호스트(예: Claude)가 MCP 서버에 연결하여 AI가 데이터베이스를 쿼리하거나 API를 호출하거나 통합된 표준 인터페이스를 통해 작업을 실행할 수 있도록 합니다.

**Helius에는 왜 중요한가요:** MCP는 Claude에게 실시간 Solana 데이터 및 Helius 인프라 — 잔액, 자산 메타데이터, 구문 분석된 트랜잭션, 웹훅 관리, 스트리밍 등에 직접 액세스할 수 있는 권한을 부여합니다. 이를 통해 Claude는 API 응답을 추측하거나 반복적으로 curl 요청을 보내야 얻을 수 있는 컨텍스트를 획득할 수 있습니다. Helius를 통한 MCP는 Claude가 구조화된 도구 호출을 사용하여 실제로 Solana와 상호작용하도록 합니다.

<Note>
  [helius.dev/docs](https://www.helius.dev/docs)에 있는 Helius 문서 사이트는 Mintlify에 의해 자동 생성된 별도의 MCP 서버를 노출합니다. 그 서버는 문서 검색에만 국한되어 있습니다. 여기에서 설명하는 `helius-mcp`는 모든 Helius 및 Solana 기능을 포괄하는 종합 서버입니다.
</Note>

## 빠른 시작

<Steps>
  <Step title="MCP 서버 추가">
    ```bash theme={"system"}
    claude mcp add helius npx helius-mcp@latest
    ```

    또는 MCP 호스트의 설정(Claude Desktop, Cursor, Windsurf, VS Code 등)에 추가하십시오:

    ```json theme={"system"}
    {
      "mcpServers": {
        "helius": {
          "command": "npx",
          "args": ["helius-mcp@latest"]
        }
      }
    }
    ```
  </Step>

  <Step title="API 키 구성">
    **키가 이미 있는 경우:**

    ```bash theme={"system"}
    export HELIUS_API_KEY=YOUR_API_KEY
    ```

    또는 Claude 내부에서 `setHeliusApiKey` 작업을 호출하여 설정하십시오 `heliusAccount`. API 키는 다음 순서로 해결됩니다:

    1. 세션 내 `setHeliusApiKey` 작업 호출
    2. `HELIUS_API_KEY` 환경 변수
    3. `~/.helius/config.json` ( [Helius CLI](/docs/ko/agents/cli)를 통해 설정)

    **새로운 계정이 필요한 경우:** 아래의 [가입](#가입)을 참조하십시오.
  </Step>

  <Step title="도구 사용 시작">
    평범한 영어로 질문하십시오 — 적절한 도구와 작업이 자동으로 선택됩니다:

    * "이 지갑이 소유한 NFT는 무엇인가요?"
    * "이 트랜잭션 구문 분석: `5abc...`"
    * "`Gh9ZwEm...`의 잔액을 얻으십시오"
    * "`7xKp...`에게 1 SOL 보내기"
    * "이 주소에 대한 웹훅 생성하기"
  </Step>
</Steps>

## Helius MCP 서버에 연결하기

<Tabs>
  <Tab title="Claude Code">
    다음 명령을 실행하십시오:

    ```bash theme={"system"}
    claude mcp add helius npx helius-mcp@latest
    ```

    또는 프로젝트의 `.mcp.json`에 추가하십시오:

    ```json theme={"system"}
    {
      "mcpServers": {
        "helius": {
          "command": "npx",
          "args": ["helius-mcp@latest"]
        }
      }
    }
    ```

    다음과 같이 확인하십시오:

    ```bash theme={"system"}
    claude mcp list
    ```

    <Tip>
      한 번의 단계로 기술과 MCP를 원하십니까? 대신 [Helius 플러그인](/docs/ko/agents/claude-code-plugin)을 설치하십시오:

      ```bash theme={"system"}
      claude plugin install helius @claude-plugins-official
      ```

      또는 Helius 마켓플레이스에서 설치하십시오:

      ```
      /plugin marketplace add helius-labs/core-ai
      /plugin install helius@helius-labs
      ```
    </Tip>
  </Tab>

  <Tab title="Claude Desktop">
    **설정 > 개발자 > 구성 편집**을 열고 서버를 추가하십시오:

    ```json theme={"system"}
    {
      "mcpServers": {
        "helius": {
          "command": "npx",
          "args": ["helius-mcp@latest"]
        }
      }
    }
    ```

    Claude Desktop을 재시작하여 적용하십시오.
  </Tab>

  <Tab title="Cursor">
    명령 팔레트를 열고(`Cmd/Ctrl + Shift + P`), **MCP: 서버 추가**를 검색하고 입력하십시오:

    * **이름:** `helius`
    * **명령:** `npx helius-mcp@latest`

    또는 프로젝트의 `.cursor/mcp.json`에 추가하십시오:

    ```json theme={"system"}
    {
      "mcpServers": {
        "helius": {
          "command": "npx",
          "args": ["helius-mcp@latest"]
        }
      }
    }
    ```
  </Tab>

  <Tab title="VS Code">
    프로젝트 루트에 `.vscode/mcp.json` 파일을 생성하십시오:

    ```json theme={"system"}
    {
      "servers": {
        "helius": {
          "command": "npx",
          "args": ["helius-mcp@latest"]
        }
      }
    }
    ```

    MCP 지원이 활성화된 [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) 확장이 필요합니다.
  </Tab>

  <Tab title="Windsurf">
    명령 팔레트를 열고(`Cmd/Ctrl + Shift + P`), **MCP 서버 구성**을 검색하고 추가하십시오:

    ```json theme={"system"}
    {
      "mcpServers": {
        "helius": {
          "command": "npx",
          "args": ["helius-mcp@latest"]
        }
      }
    }
    ```
  </Tab>

  <Tab title="Codex">
    다음 명령을 실행하십시오:

    ```bash theme={"system"}
    codex mcp add helius -- npx helius-mcp@latest
    ```

    또는 `~/.codex/config.toml` (또는 프로젝트에 제한된 경우 `.codex/config.toml`)에 추가하십시오:

    ```toml theme={"system"}
    [mcp_servers.helius]
    command = "npx"
    args = ["helius-mcp@latest"]
    ```

    다음과 같이 확인하십시오:

    ```bash theme={"system"}
    codex mcp list
    ```
  </Tab>
</Tabs>

## 공용 도구 표면

Helius MCP는 **10개의 공용 도구**를 노출합니다: 9개의 라우팅 도메인 도구와 `expandResult`. 모든 Helius 및 Solana 작업은 적절한 라우팅 도구에서 `action` 인수로 접근할 수 있습니다.

| 도구                  | 범위                                       |
| ------------------- | ---------------------------------------- |
| `heliusAccount`     | 계정 설정, 인증, 계획, 청구                        |
| `heliusWallet`      | 지갑 잔액, 소유, 기록, 신원                        |
| `heliusAsset`       | 자산, NFT, 컬렉션, 토큰 보유자                     |
| `heliusTransaction` | 트랜잭션 구문 분석 및 지갑 거래 내역                    |
| `heliusChain`       | 체인 상태, 토큰 계정, 블록, 네트워크 상태, 프로그램 계정       |
| `heliusStreaming`   | 웹훅 CRUD 및 구독 구성(WebSockets, LaserStream) |
| `heliusKnowledge`   | 문서, 가이드, 가격, 문제 해결, 소스, 블로그, SIMD        |
| `heliusWrite`       | 전송 — SOL과 SPL 토큰                         |
| `heliusCompression` | 압축된 NFT에 대한 머클 증명                        |
| `expandResult`      | 요약 우선 출력 확장 by `resultId`                |

<Card title="전체 도구 카탈로그" icon="bolt" href="/docs/ko/agents/mcp/tools">
  각 라우팅 도구별로 그룹화된 모든 작업, 호출 형상 세부 정보 및 `expandResult` 사용법
</Card>

### 라우팅 도구 호출 형상

9개의 라우팅 도구 각각은 공통 형상을 공유합니다:

* `action` — 실행할 Helius 작업 이름, 예: `getBalance` 또는 `createWebhook`
* 도메인별 매개변수 — 예를 들어 `address`, `signatures` 또는 `webhookURL`
* 선택적 `detail` — `summary`, `standard`, 또는 `full`
* 원격 측정 필드 — `_feedback`, `_feedbackTool`, `_model`

예시 호출:

```json theme={"system"}
{
  "name": "heliusWallet",
  "arguments": {
    "action": "getBalance",
    "address": "Gh9ZwEmdLJ8DscKNTkTqPbNwLNNBjuSzaG9Vp2KGtKJr",
    "_feedback": "initial balance check",
    "_feedbackTool": "heliusWallet.getBalance",
    "_model": "your-model-id"
  }
}
```

### 요약 우선 응답 및 `expandResult`

대량 응답은 **요약 우선**입니다. 라우팅 도구는 큰 응답이거나 `detail: "summary"`가 요청된 경우, 간결한 요약과 함께 `resultId`를 반환합니다. 이 `resultId`를 `expandResult`와 함께 사용하여 원하는 섹션, 범위, 페이지 또는 연속 슬라이스를 가져옵니다.

이렇게 하면 탐색 쿼리에 대한 토큰 사용량을 줄이면서도 에이전트가 필요한 경우 전체 페이로드를 자세히 볼 수 있습니다.

## 가입

AI 도구에서 호스트된 결제 링크를 통해 또는 로컬 키패어에서 USDC를 직접 결제하여 Helius 계정을 생성합니다. 가입 흐름은 `heliusAccount` 라우팅 도구를 통해 실행됩니다:

<Steps>
  <Step title="키패어 생성">
    AI가 `heliusAccount`를 `action: "generateKeypair"`로 호출하면 Solana 지갑이 생성되고 주소가 반환됩니다.
  </Step>

  <Step title="결제 인텐트 생성">
    AI는 `heliusAccount`를 `action: "signup"` 및 `mode: "link"`로 호출하여 `paymentUrl`(예: `https://dashboard.helius.dev/pay/<id>`)을 반환합니다. 사용자가 원하는 지갑으로 결제할 수 있도록 열립니다. 또는 `mode: "autopay"`를 전달하여 로컬 키패어에서 자동으로 USDC를 전송합니다(지갑에 약 0.001 SOL + 가입 금액 상당의 USDC가 있어야 합니다).
  </Step>

  <Step title="결제 후 재개">
    링크를 통해 결제한 후, AI는 `heliusAccount`를 `action: "signup"` 및 `mode: "resume"`로 호출하여 결제 인텐트를 폴링하고, 계정 프로비저닝을 완료하며, 자동으로 API 키를 구성합니다.
  </Step>
</Steps>

<Note>
  **연락처 정보:** 모든 신규 가입 — 에이전트 플랜을 포함하여 — 는 `email`, `firstName` 및 `lastName`가 필요합니다. `upgradePlan`도 마찬가지로 필요합니다.
</Note>

또는 [Helius CLI](/docs/ko/agents/cli)를 사용하여 터미널에서 동일한 작업을 수행하십시오:

```bash theme={"system"}
npx helius-cli@latest keygen
npx helius-cli@latest signup --plan agent --email you@example.com --first-name Jane --last-name Doe   # Print hosted payment link
# (pay in browser, then:)
npx helius-cli@latest signup --resume         # Finalize account
# Or autopay from the local keypair:
npx helius-cli@latest signup --plan agent --pay --email you@example.com --first-name Jane --last-name Doe
```

## 네트워크 구성

MCP 서버의 기본 설정은 **mainnet-beta**입니다. 환경 변수를 통해 devnet으로 전환하십시오:

```bash theme={"system"}
export HELIUS_NETWORK=devnet
```

또는 세션 내에서 `heliusAccount`의 `setNetwork` 작업을 호출하십시오.

## 시스템 프롬프트

`helius-mcp` 패키지는 AI 모델이 Helius 도구를 효과적으로 사용하는 방법을 가르치는 사전 빌드된 시스템 프롬프트와 함께 제공됩니다. 이는 `system-prompts/`에 위치합니다:

```
system-prompts/
├── helius/              # Core Helius skill
├── helius-phantom/      # Phantom frontend skill
├── helius-jupiter/      # Jupiter DeFi skill
├── helius-dflow/        # DFlow trading skill
├── helius-okx/          # OKX trading & intelligence skill
└── svm/                 # SVM architecture skill
```

각각 세 가지 변형이 포함되어 있습니다:

* `openai.developer.md` — OpenAI 응답/채팅 완료 API(`developer` 메시지)에 사용
* `claude.system.md` — Claude API(시스템 프롬프트)에 사용
* `full.md` — 모든 참조가 인라인된 독립형 버전(Cursor Rules, ChatGPT 등에 사용)

코드 예제는 [`helius-skills/SYSTEM-PROMPTS.md`](https://github.com/helius-labs/core-ai/blob/main/helius-skills/SYSTEM-PROMPTS.md) 통합 가이드를 참조하십시오.

## 기술

기술은 Claude에게 요청을 올바른 MCP 동작 및 참조 파일로 라우팅하는 방법을 가르치는 전문가 지침 세트입니다. 기본 도구 액세스를 넘어 라우팅 로직, 올바른 SDK 패턴, 일반적인 실수를 방지하는 규칙을 포함합니다.

<Card title="기술 개요" icon="brain" href="/docs/ko/agents/skills/overview">
  여섯 가지 기술 사용 가능: Build(일반 Solana 개발), Phantom(프론트엔드 dApps), Jupiter(DeFi), DFlow(트레이딩 앱), OKX(트레이딩 및 인텔리전스), 그리고 SVM(프로토콜 내부)
</Card>

## 자세히 알아보기

<CardGroup cols={2}>
  <Card title="Claude Code 플러그인" icon="puzzle-piece" href="/docs/ko/agents/claude-code-plugin">
    MCP + 기술을 원클릭 설치
  </Card>

  <Card title="Helius CLI" icon="terminal" href="/docs/ko/agents/cli">
    명령줄 계정 관리
  </Card>

  <Card title="MCP 명세" icon="book" href="https://modelcontextprotocol.io/">
    모델 컨텍스트 프로토콜 표준 알아보기
  </Card>

  <Card title="helius-mcp on npm" icon="npm" href="https://www.npmjs.com/package/helius-mcp">
    패키지 세부 정보 및 버전 기록
  </Card>

  <Card title="변경 로그" icon="list" href="https://github.com/helius-labs/core-ai/blob/main/helius-mcp/CHANGELOG.md">
    버전 기록 및 릴리스 노트
  </Card>

  <Card title="기여하기" icon="github" href="https://github.com/helius-labs/core-ai/blob/main/helius-mcp/CONTRIBUTING.md">
    `helius-mcp` 기여 가이드
  </Card>
</CardGroup>