MCP 서버

Claude Code, Cursor, Windsurf 같은 AI 코딩 어시스턴트에서 IPFS Ninja를 직접 사용하세요. 파일 업로드, CID 핀 고정, 폴더 관리, 사용량 확인 — 모두 AI 대화에서 가능합니다.

MCP란?

Model Context Protocol (MCP)은 AI 어시스턴트를 외부 도구 및 데이터 소스에 연결하기 위한 오픈 표준입니다. IPFS Ninja MCP 서버는 대화 중 AI 모델이 호출할 수 있는 11개의 도구를 제공하여 IPFS Ninja 계정과 상호작용할 수 있게 합니다.

설치

npm 패키지

@ipfs-ninja/mcp-server

npm에서 사용할 수 있습니다. 글로벌 설치 불필요 — npx로 실행합니다.

사전 요구사항

• Node.js 18+ 설치
• IPFS Ninja API 키 (Dashboard > API Keys에서 발급)

Claude Code 설정

1단계: API 키 받기

1. ipfs.ninja에 가입 (무료)
2. Dashboard > API Keys로 이동
3. Create API key를 클릭하고 전체 키를 복사 (한 번만 표시됩니다)

2단계: MCP 서버 추가

터미널에서 다음 명령을 실행하세요:

claude mcp add ipfs-ninja \
  --transport stdio \
  -e IPFS_NINJA_API_KEY=bws_your_full_api_key_here \
  -- npx -y @ipfs-ninja/mcp-server

또는 .claude/settings.json에 직접 추가하세요:

{
  "mcpServers": {
    "ipfs-ninja": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@ipfs-ninja/mcp-server"],
      "env": {
        "IPFS_NINJA_API_KEY": "bws_your_full_api_key_here"
      }
    }
  }
}

3단계: Claude Code 재시작

Claude Code를 종료하고 다시 엽니다. /mcp를 입력하여 IPFS Ninja 서버가 연결되어 있는지 확인하세요.

4단계: 사용 시작

Claude에게 자연스럽게 말하기만 하면 됩니다:

You: Upload my README.md to IPFS
You: List my recent files
You: How much storage am I using?
You: Pin bafyabc123... from the IPFS network
You: Create a folder called "project-assets"

Cursor / Windsurf 설정

MCP 설정에 추가하세요 (Settings > MCP Servers):

설정	값
Name	ipfs-ninja
Transport	stdio
Command	npx
Args	-y @ipfs-ninja/mcp-server
Environment	IPFS_NINJA_API_KEY=bws_...

사용 가능한 도구

파일 작업

도구	설명	프롬프트 예시
ipfs_upload	파일 콘텐츠 업로드 (base64 또는 텍스트)	"이 HTML 파일을 IPFS에 업로드해줘"
ipfs_upload_json	JSON 객체 업로드	"이 설정을 IPFS에 영구 JSON으로 저장해줘"
ipfs_list	업로드한 파일 목록 표시	"최근 업로드를 보여줘"
ipfs_get	CID로 파일 메타데이터 조회	"QmXyz...는 어떤 종류의 파일이야?"
ipfs_delete	핀 해제 및 파일 삭제	"QmXyz...를 내 계정에서 삭제해줘"

피닝

도구	설명	프롬프트 예시
ipfs_pin	네트워크의 기존 CID 핀 고정	"bafyabc...를 내 계정에 핀 고정해줘"
ipfs_pin_status	핀 진행 상태 확인	"bafyabc... 핀 고정 완료됐어?"

정리

도구	설명	프롬프트 예시
ipfs_folders_list	폴더 목록 표시	"내 폴더를 보여줘"
ipfs_folders_create	새 폴더 생성	"nft-metadata라는 폴더를 만들어줘"

계정

도구	설명	프롬프트 예시
ipfs_profile	플랜, 스토리지, 대역폭 정보 조회	"내 스토리지 사용량은 얼마야?"
ipfs_analytics	일별 대역폭 및 파일 통계 조회	"이번 주 대역폭 사용량을 보여줘"

워크플로 예시

정적 사이트 배포

You: Upload the contents of my dist/ folder to IPFS
Claude: [uploads each file, returns CIDs]

You: What's the CID for index.html?
Claude: [calls ipfs_get]
     → QmXyz... — https://ipfs.ninja/ipfs/QmXyz...

NFT 메타데이터

You: Create a folder called "my-collection" and upload this metadata JSON
Claude: [calls ipfs_folders_create, then ipfs_upload_json]
     → Folder: my-collection
     → CID: QmAbc... — permanent metadata URL ready for your smart contract

사용량 모니터링

You: Am I close to my storage limit?
Claude: [calls ipfs_profile]
     → Plan: Bodhi, Storage: 45.2 MB / 100 GB (0.04%)
     → You have plenty of room.

You: Show my bandwidth this week
Claude: [calls ipfs_analytics with days=7]
     → 2.3 MB bandwidth, 45 requests across 3 days

네트워크에서 콘텐츠 핀 고정

You: Pin the IPFS readme at QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG
Claude: [calls ipfs_pin]
     → Pin initiated! Status: pinning

You: Is it done?
Claude: [calls ipfs_pin_status]
     → Status: pinned, Size: 0.008 MB

문제 해결

"IPFS_NINJA_API_KEY environment variable is required"

API 키가 설정되지 않았습니다. MCP 설정의 env 섹션에 올바른 키가 있는지 확인하세요.

"API error 402: not enough storage"

플랜의 스토리지 한도에 도달했습니다. ipfs.ninja/pricing에서 업그레이드하거나 사용하지 않는 파일을 삭제하세요.

"API error 403: Forbidden"

API 키가 유효하지 않거나 만료되었을 수 있습니다. Dashboard > API Keys에서 새 키를 생성하세요.

서버가 /mcp에 표시되지 않음

MCP 서버를 추가한 후 Claude Code를 재시작했는지 확인하세요. Node.js 18+가 설치되어 있는지 확인하세요 (node --version).