Starknet MCP 서버

Starknet 블록체인을 위한 포괄적인 모델 컨텍스트 프로토콜(MCP) 서버입니다. 이 서버는 AI 에이전트에게 Starknet 네트워크와 상호 작용하고, 블록체인 데이터를 쿼리하고, 지갑을 관리하고, 스마트 계약과 상호 작용할 수 있는 기능을 제공합니다.

📋 목차

개요
특징
지원되는 네트워크
필수 조건
설치
서버 구성
용법
API 참조
AI 어시스턴트 사용
보안 고려 사항
프로젝트 구조
개발 협약
선적 서류 비치
특허

🔭 개요

Starknet MCP 서버는 모델 컨텍스트 프로토콜(Model Context Protocol)을 활용하여 AI 에이전트에 블록체인 서비스를 제공합니다. Starknet 생태계에 대한 포괄적인 인터페이스를 제공하여 AI 어시스턴트가 자연어를 통해 Starknet 블록체인 데이터 및 운영과 상호 작용할 수 있도록 지원합니다.

주요 기능은 다음과 같습니다.

블록체인 상태(잔액, 거래, 블록) 읽기
카이로 스마트 계약과 상호 작용
토큰 전송(ETH, STRK 및 기타 ERC20 토큰)
NFT 및 토큰 메타데이터 작업
StarknetID 도메인 확인(Ethereum의 ENS와 유사)
적절한 트랜잭션 처리를 통해 읽기 및 쓰기 작업 모두 수행

모든 서비스는 일관된 MCP 도구 및 리소스 인터페이스를 통해 제공되므로 AI 에이전트가 Starknet 블록체인 기능을 쉽게 발견하고 사용할 수 있습니다. Starknet 주소를 허용하는 모든 도구는 StarknetID도 지원하여 사람이 읽을 수 있는 ID를 자동으로 식별하여 백그라운드에서 주소를 확인합니다.

✨ 특징

Starknet 통합 : Starknet.js를 사용한 전체 Starknet 블록체인 통합
네트워크 지원 : 메인넷과 세폴리아 테스트넷 모두 지원
StarknetID 통합 : Starknet ID를 주소로 변환 및 그 반대의 경우
네이티브 토큰 지원 : ETH 및 STRK 네이티브 토큰 모두 지원
스마트 계약 상호 작용 : Starknet 스마트 계약 호출 및 쿼리
이중 전송 : 다양한 통합 요구 사항에 맞게 stdio 서버 또는 HTTP 서버로 실행
AI 준비 : Claude, GPT 및 기타 AI 어시스턴트와 함께 사용하도록 설계되었습니다.

블록체인 정보

체인 정보(체인 ID, 최신 블록) 쿼리
블록 세부 정보 및 거래 살펴보기
거래 영수증 및 상태 보기
주소 정보 및 계약 데이터를 가져옵니다.

네이티브 토큰 작업

모든 주소에 대한 ETH 및 STRK 잔액을 받으세요
계정 간 ETH와 STRK 전송
결합된 네이티브 토큰 잔액 보기

토큰 운영

ERC20 토큰 잔액 및 정보를 확인하세요
ERC20 토큰 전송
토큰 공급 및 메타데이터 보기
토큰 소유권 확인

NFT 운영

토큰 ID로 NFT 소유권 확인
NFT 컬렉션 정보 받기
주소별 NFT 잔액 보기

스마트 계약 상호 작용

읽기 전용 계약 함수 호출
거래 확인으로 계약 쓰기 실행
계약 보관 정보 가져오기
ABI 및 계약 클래스 정보 보기

스타크넷ID

Starknet 주소를 Starknet ID로 변환
Starknet ID를 주소로 변환
검증 데이터를 포함한 완전한 Starknet ID 프로필을 얻으세요
Starknet 도메인 검증

🔧 지원 네트워크

이 서버는 다음의 Starknet 네트워크를 지원합니다:

메인넷 : 주요 스타크넷 생산 네트워크
세폴리아(Sepolia ) : 이더리움 세폴리아에 대한 스타크넷의 테스트넷

🛠️ 필수 조건

Bun 1.0.0 이상(권장)
Node.js 18.0.0 이상

📦 설치

옵션 1: 설치 없이 사용(npx)

시작하는 가장 쉬운 방법은 npx 사용하여 패키지를 직접 실행하는 것입니다.

지엑스피1

이렇게 하면 먼저 설치할 필요 없이 최신 버전이 자동으로 다운로드되어 실행됩니다.

옵션 2: 글로벌 설치

자주 사용할 계획이라면 전역으로 설치할 수 있습니다.

# Install globally
npm install -g @mcpdotdirect/starknet-mcp-server

# Then run from anywhere
starknet-mcp-server
starknet-mcp-server http

옵션 3: 로컬 프로젝트 설치

# Add to your project
npm install @mcpdotdirect/starknet-mcp-server

# Using yarn
yarn add @mcpdotdirect/starknet-mcp-server

# Using pnpm
pnpm add @mcpdotdirect/starknet-mcp-server

그런 다음 package.json 스크립트에 다음을 추가합니다.

"scripts": {
  "starknet-mcp": "starknet-mcp-server",
  "starknet-mcp-http": "starknet-mcp-server http"
}

옵션 4: 소스에서 실행

소스에서 실행하거나 로컬로 개발하려는 경우:

# Clone the repository
git clone https://github.com/mcpdotdirect/starknet-mcp-server.git
cd starknet-mcp-server

# Install dependencies
npm install

# Start the stdio server
npm start

# Or start the HTTP server
npm run start:http

자동 재로드를 사용한 개발의 경우:

# Development mode with stdio
npm run dev

# Development mode with HTTP
npm run dev:http

⚙️ 서버 구성

서버는 다음과 같은 기본 구성을 사용합니다.

기본 네트워크 : 메인넷
서버 포트 : 3000 (HTTP 모드)
서버 호스트 : 0.0.0.0(모든 네트워크 인터페이스에서 접근 가능)

이러한 값은 애플리케이션에 하드코딩되어 있습니다. 수정해야 하는 경우 다음 파일을 편집할 수 있습니다.

네트워크 구성: src/core/chains.ts
서버 구성: src/server/http-server.ts

🔍 사용법

서버 실행

Starknet MCP 서버는 두 가지 모드로 실행할 수 있습니다.

# Run the server in stdio mode (for CLI tools and AI assistants)
npx @mcpdotdirect/starknet-mcp-server

# Run the server in HTTP mode (for web applications)
npx @mcpdotdirect/starknet-mcp-server http

HTTP 서버는 기본적으로 포트 3000에서 실행되며 실시간 통신을 위해 REST API와 SSE(Server-Sent Events)를 모두 제공합니다.

커서에서 연결

Cursor에서 Starknet MCP 서버에 연결하려면:

커서를 열고 설정(왼쪽 하단의 기어 아이콘)으로 이동하세요.
왼쪽 사이드바에서 "기능"을 클릭하세요
"MCP 서버" 섹션까지 아래로 스크롤하세요.
"새 MCP 서버 추가"를 클릭하세요.
다음 세부 정보를 입력하세요.
- 서버 이름: starknet-mcp-server
- 유형: command
- 명령어: npx @mcpdotdirect/starknet-mcp-server
"저장"을 클릭하세요

연결되면 Cursor 내에서 MCP 서버의 기능을 직접 사용할 수 있습니다. 서버는 MCP 서버 목록에 나타나며 필요에 따라 활성화/비활성화할 수 있습니다.

Cursor와 함께 mcp.json 사용

팀과 공유하거나 여러 프로젝트에서 사용할 수 있는 휴대성이 뛰어난 구성을 원하시면 프로젝트의 루트 디렉토리에 .cursor/mcp.json 파일을 만드세요.

{
  "mcpServers": {
    "starknet-mcp-server": {
      "command": "npx",
      "args": [
        "@mcpdotdirect/starknet-mcp-server"
      ]
    },
    "starknet-mcp-http": {
      "command": "npx",
      "args": [
        "@mcpdotdirect/starknet-mcp-server",
        "http"
      ]
    }
  }
}

이 파일을 프로젝트의 .cursor 디렉토리에 넣으면(존재하지 않으면 만듭니다) Cursor가 해당 프로젝트에서 작업할 때 자동으로 이러한 MCP 서버 구성을 감지하여 사용합니다.

SSE를 사용한 HTTP 모드

웹 애플리케이션을 개발 중이고 SSE(Server-Sent Events)를 통해 HTTP 서버에 연결하려는 경우 다음 구성을 사용할 수 있습니다.

{
  "mcpServers": {
    "starknet-mcp-sse": {
      "url": "http://localhost:3000/sse"
    }
  }
}

Claude CLI를 사용하여 연결

Claude CLI를 사용하는 경우 다음 두 가지 명령만으로 MCP 서버에 연결할 수 있습니다.

# Add the MCP server using npx
claude mcp add starknet-mcp-server npx @mcpdotdirect/starknet-mcp-server

# Start Claude with the MCP server enabled
claude

예: 커서에서 MCP 서버 사용

MCP 서버를 구성한 후에는 Cursor에서 쉽게 사용할 수 있습니다. 예:

프로젝트에 새로운 JavaScript/TypeScript 파일을 만듭니다.

// starknet-example.js
async function main() {
  try {
    // When using with Cursor, you can simply ask Cursor to:
    // "Check the ETH balance of address 0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7 on Starknet mainnet"
    // Or "Lookup the Starknet ID for address 0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7"
    
    // Cursor will use the MCP server to execute these operations 
    // without requiring any additional code from you
  } catch (error) {
    console.error("Error:", error.message);
  }
}

main();

Cursor에서 파일을 열어 놓으면 Cursor에 다음 작업을 요청할 수 있습니다.
- "vitalik.stark의 ETH 잔액을 확인하세요"
- "스타크넷의 최신 블록에 대한 정보를 얻으세요"
- "컬렉션 0x에서 NFT #123의 소유자를 찾아보세요..."

예: Starknet ID로 ETH 잔액 얻기

// Example of using the MCP client to check an ETH balance using Starknet ID
const mcp = new McpClient("http://localhost:3000");

const result = await mcp.invokeTool("get_starknet_eth_balance", {
  address: "vitalik.stark", // Starknet ID instead of address
  network: "mainnet"
});

console.log(result);
// {
//   wei: "1000000000000000000",
//   ether: "1.0"
// }

예: Starknet ID 확인

// Example of using the MCP client to resolve a Starknet ID to an address
const mcp = new McpClient("http://localhost:3000");

const result = await mcp.invokeTool("resolve_starknet_address", {
  name: "vitalik.stark",
  network: "mainnet"
});

console.log(result);
// {
//   starknetId: "vitalik.stark",
//   address: "0x04d07e40e93398ed3c76981e449d3446f7c4e52aac5b3e8a37d7b0ca30845a5d",
//   resolved: true
// }

예: 스마트 계약 호출

// Example of using the MCP client to call a smart contract function
const mcp = new McpClient("http://localhost:3000");

const result = await mcp.invokeTool("call_starknet_contract", {
  contractAddress: "0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7", // ETH contract
  entrypoint: "totalSupply",
  calldata: [],
  network: "mainnet"
});

console.log(result);
// {
//   result: ["0x84b6c7d5970d5a73abe"]
// }

Node.js 프로젝트에서 사용

Node.js 프로젝트에서 MCP 서버를 프로그래밍 방식으로 사용하려면 다음을 수행하세요.

// Start the MCP server as a child process
const { spawn } = require('child_process');
const mcpServer = spawn('npx', ['@mcpdotdirect/starknet-mcp-server']);

// Connect to it with the MCP client
const mcp = new McpClient({ process: mcpServer });

// Now you can use the client
const networks = await mcp.invokeTool("get_supported_starknet_networks", {
  random_string: "any"
});
console.log("Supported networks:", networks);

더욱 고급 방식으로 사용하려면 HTTP API를 중심으로 래퍼 클래스를 만들거나 Axios와 같은 라이브러리를 사용하여 더욱 깔끔한 API 호출을 구현할 수 있습니다.

📚 API 참조

사용 가능한 MCP 도구

이 서버는 다음 MCP 도구를 구현합니다.

네트워크 도구

get_starknet_chain_info : Starknet 네트워크에 대한 정보를 가져옵니다.
get_supported_starknet_networks : 지원되는 Starknet 네트워크 목록을 가져옵니다.

균형 도구

get_starknet_eth_balance : Starknet 주소 또는 Starknet ID에 대한 ETH 잔액을 가져옵니다.
get_starknet_token_balance : 주소에 대한 모든 토큰의 잔액을 가져옵니다.
get_starknet_strk_balance : 주소에 대한 STRK 토큰 잔액을 가져옵니다.
get_starknet_native_balances : 주소에 대한 모든 기본 토큰 잔액(ETH 및 STRK)을 가져옵니다.

StarknetID 도구

resolve_starknet_name : 주소의 Starknet ID를 가져옵니다.
resolve_starknet_address : Starknet ID의 주소를 가져옵니다.
get_starknet_profile : 주소에 대한 전체 Starknet ID 프로필을 가져옵니다.
validate_starknet_domain : 문자열이 유효한 Starknet ID인지 확인합니다.

블록 도구

get_starknet_block : 특정 블록에 대한 정보를 가져옵니다.
get_starknet_block_transactions : 특정 블록의 거래 내역을 가져옵니다.

거래 도구

get_starknet_transaction : 거래에 대한 세부 정보를 가져옵니다.
get_starknet_transaction_receipt : 거래 영수증 받기
check_starknet_transaction_status : 거래가 확인되었는지 확인합니다.

계약 도구

call_starknet_contract : 계약에서 읽기 전용 함수를 호출합니다.
get_starknet_contract_class : 계약의 클래스(ABI 및 기타 정보)를 가져옵니다.
execute_starknet_contract : 계약 호출(쓰기 작업)을 실행합니다.

토큰 도구

get_starknet_token_info : 토큰에 대한 정보를 가져옵니다.
get_starknet_token_supply : 토큰의 총 공급량을 가져옵니다.
check_starknet_nft_ownership : 주소가 특정 NFT를 소유하고 있는지 확인합니다.
get_starknet_nft_balance : 주소가 소유한 NFT 수를 가져옵니다.

전송 도구

transfer_starknet_eth : 한 계좌에서 다른 계좌로 ETH를 이체합니다(금액은 사람이 읽을 수 있는 형식으로 표시).
transfer_starknet_strk : 한 계좌에서 다른 계좌로 STRK를 이체합니다(금액은 사람이 읽을 수 있는 형식으로 표시).
transfer_starknet_token : 한 계정에서 다른 계정으로 ERC20 토큰을 이체합니다(금액은 사람이 읽을 수 있는 형식으로 표시).

사용 가능한 MCP 리소스

서버는 다음과 같은 MCP 리소스를 제공합니다.

네트워크 리소스

starknet://{network}/chain : 특정 네트워크에 대한 체인 정보를 가져옵니다.
starknet://networks : 지원되는 모든 네트워크 목록을 가져옵니다.

블록 리소스

starknet://{network}/block/{blockIdentifier} : 특정 블록에 대한 정보를 가져옵니다.
starknet://{network}/block/latest : 최신 블록을 가져옵니다

주소 리소스

starknet://{network}/address/{address} : 주소에 대한 정보를 가져옵니다.

거래 리소스

starknet://{network}/tx/{txHash} : 거래 정보 가져오기

StarknetID 리소스

starknet://{network}/id/address/{address} : 주소를 Starknet ID로 변환합니다.
starknet://{network}/id/name/{name} : Starknet ID를 주소로 변환합니다.
starknet://{network}/id/profile/{address} : 주소에 대한 Starknet ID 프로필을 가져옵니다.

사용 가능한 MCP 프롬프트

LLM 상호작용의 경우 서버는 다음과 같은 프롬프트를 제공합니다.

explore_starknet_block : 특정 Starknet 블록에 대한 정보를 탐색합니다.
explore_starknet_address : Starknet 주소에 대한 정보를 가져옵니다.
explore_starknet_transaction : Starknet 거래에 대한 정보를 가져옵니다.
lookup_starknet_id : Starknet ID를 조회하거나 주소를 Starknet ID로 변환합니다.
explore_starknet_id_profile : 전체 Starknet ID 프로필을 탐색합니다.

🔍 AI 어시스턴트 활용

Claude나 GPT와 같은 AI 도우미와 함께 이 서버를 사용하는 경우:

이 MCP 서버를 사용하도록 AI 어시스턴트를 구성하세요.
그러면 보조자는 도구를 사용하여 Starknet과 상호 작용할 수 있습니다.
예시 쿼리:
- "0x04d07e40e93398ed3c76981e449d3446f7c4e52aac5b3e8a37d7b0ca30845a5d 주소의 ETH 잔액은 얼마입니까?"
- "주소 0x04d07e40e93398ed3c76981e449d3446f7c4e52aac5b3e8a37d7b0ca30845a5d에 대한 Starknet ID를 찾아보세요."
- "스타크넷 메인넷의 최신 블록에는 무엇이 있나요?"
- "거래 0x7e3a33ab42f2e24184763563b7b8482b53e3b89831ebc3eacf29d4d11f5198에 대한 정보를 얻으세요"
- "Starknet ID vitalik.stark를 주소로 변환"

🔒 보안 고려 사항

개인 키는 거래 서명에만 사용되며 서버에 저장되지 않습니다.
모든 토큰 금액은 wei 또는 최소 단위가 아닌 사람이 읽을 수 있는 형식(예: ETH, STRK, 토큰 단위)으로 지정됩니다.
작업을 실행하기 전에 항상 입력 매개변수를 검증하고 정리하십시오.
프로덕션 사용을 위해 추가 인증 메커니즘 구현을 고려하세요.
프로덕션 환경에서 HTTP 서버에 HTTPS를 사용하세요
남용을 방지하기 위해 속도 제한을 구현하세요
고가치 서비스의 경우 확인 단계를 추가하는 것을 고려하세요.

📁 프로젝트 구조

starknet-mcp-server/
├── src/
│   ├── index.ts                # Main stdio server entry point
│   ├── server/                 # Server-related files
│   │   ├── http-server.ts      # HTTP server with SSE
│   │   └── server.ts           # General server setup
│   ├── core/
│   │   ├── chains.ts           # Chain definitions and utilities
│   │   ├── resources.ts        # MCP resources implementation
│   │   ├── tools.ts            # MCP tools implementation
│   │   ├── prompts.ts          # MCP prompts implementation
│   │   └── services/           # Core blockchain services
│   │       ├── index.ts        # Service exports
│   │       ├── balance.ts      # Balance services
│   │       ├── blocks.ts       # Block services
│   │       ├── clients.ts      # Client utilities
│   │       ├── contracts.ts    # Contract interactions
│   │       ├── starknetid.ts   # Starknet ID services
│   │       ├── tokens.ts       # Token services
│   │       ├── transactions.ts # Transaction services
│   │       ├── transfer.ts     # Transfer services
│   │       └── utils.ts        # Utility functions
├── package.json
├── tsconfig.json
└── README.md

🛠️ 개발 컨벤션

사용자 정의 도구, 리소스 또는 프롬프트를 추가할 때:

모든 리소스, 도구 및 프롬프트 이름에 하이픈( - ) 대신 밑줄( _ )을 사용하세요.
// Good: Uses underscores server.tool( "starknet_contract_call", "Description of the tool", { contract_address: z.string().describe("The contract address") }, async (params) => { // Tool implementation } );
이 명명 규칙은 Cursor 및 기타 AI 도구와의 호환성을 보장합니다.

📚 문서

자세한 내용은 다음과 같습니다.

📄 라이센스

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.

Integrations