홈 튜토리얼 카테고리 Skills 소개
ZH EN JA KO
스킬 플러그인

OpenClaw MCP Server 설정 및 사용 튜토리얼

· 18 분 소요

소개

MCP(Model Context Protocol, 모델 컨텍스트 프로토콜)는 AI 모델과 외부 도구 및 데이터 소스 간의 통신 방식을 정의하는 개방 표준입니다. OpenClaw는 MCP를 깊이 통합하여 AI 어시스턴트가 MCP Server를 통해 파일 시스템, 데이터베이스, API 등 외부 리소스와 상호작용할 수 있도록 합니다.

이 튜토리얼에서는 개념부터 시작하여 OpenClaw에서의 MCP 설정과 사용법을 습득하도록 안내합니다.

MCP란 무엇인가

핵심 개념

MCP가 해결하는 핵심 문제는 AI 모델이 외부 도구를 안전하고 표준화된 방식으로 사용할 수 있게 하는 것입니다.

사용자 메시지 → OpenClaw → AI 모델 → 도구 필요 → MCP Client → MCP Server → 작업 실행
                                                                ↓
사용자 응답 수신 ← OpenClaw ← AI 모델 ← 결과 획득 ← MCP Client ← MCP Server

MCP의 세 가지 핵심 기능

기능 설명 예시
Tools 호출 가능한 함수/도구 파일 읽기/쓰기, HTTP 요청 전송, 데이터베이스 조회
Resources 접근 가능한 데이터 리소스 파일 내용, 데이터베이스 테이블, API 엔드포인트
Prompts 사전 정의된 프롬프트 템플릿 코드 리뷰 템플릿, 요약 템플릿

MCP Server 유형

MCP Server는 두 가지 실행 방식이 있습니다:

  • Stdio(표준 입출력): 자식 프로세스로 실행되며 stdin/stdout을 통해 통신
  • SSE(Server-Sent Events): HTTP 서비스로 실행되며 HTTP를 통해 통신

OpenClaw에서 MCP Server 설정

기본 설정 구조

~/.config/openclaw/openclaw.json5에서 MCP를 설정합니다:

{
  mcp: {
    servers: {
      // 각 MCP Server는 고유한 이름을 가집니다
      "server-name": {
        // Stdio 모드 설정
        command: "npx",
        args: ["-y", "@package/mcp-server"],
        env: {
          // 환경 변수
          API_KEY: "your-key"
        }
      },

      // 또는 SSE 모드 설정
      "remote-server": {
        url: "http://localhost:3001/sse",
        headers: {
          "Authorization": "Bearer your-token"
        }
      }
    }
  }
}

다중 Server 공존

여러 MCP Server를 동시에 설정할 수 있습니다:

{
  mcp: {
    servers: {
      "filesystem": {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-filesystem",
               "--allow-read", "--allow-write", "/home/user/documents"]
      },
      "database": {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-sqlite",
               "--db-path", "/home/user/data/app.db"]
      },
      "http-fetch": {
        command: "npx",
        args: ["-y", "@openclaw-mcp/http-fetch"]
      },
      "github": {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-github"],
        env: {
          GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxxxx"
        }
      }
    }
  }
}

주요 MCP Server 상세 설명

1. 파일 시스템 MCP Server

AI가 로컬 파일을 읽고 쓸 수 있게 하며, 문서 관리 및 데이터 저장 시나리오에 적합합니다.

{
  mcp: {
    servers: {
      "filesystem": {
        command: "npx",
        args: [
          "-y",
          "@modelcontextprotocol/server-filesystem",
          "--allow-read",      // 읽기 허용
          "--allow-write",     // 쓰기 허용
          "/home/user/docs"    // 디렉토리 범위 제한
        ]
      }
    }
  }
}

제공되는 도구:

도구 이름 기능 매개변수
read_file 파일 내용 읽기 path
write_file 파일 쓰기 path, content
list_directory 디렉토리 내용 나열 path
create_directory 디렉토리 생성 path
move_file 파일 이동/이름 변경 source, destination
search_files 파일 검색 path, pattern

보안 팁: 반드시 경로 매개변수를 통해 접근 가능한 디렉토리 범위를 제한하고, 전체 파일 시스템에 대한 접근 권한을 부여하지 마십시오.

2. SQLite 데이터베이스 MCP Server

AI가 SQLite 데이터베이스를 조회하고 조작할 수 있게 합니다.

{
  mcp: {
    servers: {
      "sqlite": {
        command: "npx",
        args: [
          "-y",
          "@modelcontextprotocol/server-sqlite",
          "--db-path", "/home/user/data/myapp.db"
        ]
      }
    }
  }
}

제공되는 도구:

도구 이름 기능
read_query SELECT 쿼리 실행
write_query INSERT/UPDATE/DELETE 실행
create_table 새 테이블 생성
list_tables 모든 테이블 나열
describe_table 테이블 구조 확인

사용 예시 - 사용자가 채팅에서 "지난주 판매 데이터를 조회해줘"라고 말하면, AI가 MCP 도구를 통해 SQL 쿼리를 자동으로 실행하고 결과를 반환합니다.

3. HTTP Fetch MCP Server

AI가 HTTP 요청을 발송하여 임의의 REST API를 호출할 수 있게 합니다.

{
  mcp: {
    servers: {
      "http-fetch": {
        command: "npx",
        args: ["-y", "@openclaw-mcp/http-fetch"],
        env: {
          // 선택 사항: 기본 요청 헤더 설정
          DEFAULT_HEADERS: '{"User-Agent": "OpenClaw/1.0"}'
        }
      }
    }
  }
}

제공되는 도구:

도구 이름 기능
http_get GET 요청 발송
http_post POST 요청 발송
http_put PUT 요청 발송
http_delete DELETE 요청 발송

4. GitHub MCP Server

GitHub 저장소와 상호작용하여 Issue, PR, 코드 등을 확인합니다.

{
  mcp: {
    servers: {
      "github": {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-github"],
        env: {
          GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxxxx"
        }
      }
    }
  }
}

제공되는 도구:

도구 이름 기능
search_repositories 저장소 검색
get_file_contents 파일 내용 가져오기
list_issues Issue 나열
create_issue Issue 생성
list_pull_requests PR 나열
create_pull_request PR 생성

5. PostgreSQL MCP Server

PostgreSQL 데이터베이스에 연결합니다:

{
  mcp: {
    servers: {
      "postgres": {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-postgres"],
        env: {
          DATABASE_URL: "postgresql://user:pass@localhost:5432/mydb"
        }
      }
    }
  }
}

MCP와 Skill의 협업

MCP Server는 Skill에 외부 세계와 상호작용하는 능력을 제공합니다. SKILL.md에서 필요한 MCP 도구를 선언합니다:

---
name: my-skill
mcp_tools:
  - filesystem    # 파일 시스템 도구 사용
  - http_fetch    # HTTP 요청 도구 사용
  - sqlite        # 데이터베이스 도구 사용
---

AI는 Skill 실행 시 필요에 따라 해당 MCP 도구를 자동으로 호출합니다.

실제 플로우 예시

사용자가 "지난주 주문 데이터를 CSV 파일로 내보내줘"라고 보내면:

  1. AI가 sqlite와 filesystem 두 MCP Server가 필요한 작업임을 인식합니다
  2. sqlite.read_query를 호출하여 지난주 주문 데이터를 조회합니다
  3. 조회 결과를 CSV 형식으로 포맷합니다
  4. filesystem.write_file을 호출하여 CSV 파일을 저장합니다
  5. 파일 경로를 사용자에게 반환합니다

커스텀 MCP Server

기존 MCP Server로 요구사항을 충족할 수 없는 경우 직접 개발할 수 있습니다.

최소 예시 (Node.js)

// my-mcp-server.js
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new Server({
  name: "my-custom-server",
  version: "1.0.0"
}, {
  capabilities: {
    tools: {}
  }
});

// 도구 등록
server.setRequestHandler("tools/list", async () => ({
  tools: [{
    name: "greet",
    description: "Generate a greeting message",
    inputSchema: {
      type: "object",
      properties: {
        name: { type: "string", description: "Name to greet" }
      },
      required: ["name"]
    }
  }]
}));

// 도구 호출 처리
server.setRequestHandler("tools/call", async (request) => {
  if (request.params.name === "greet") {
    const name = request.params.arguments.name;
    return {
      content: [{ type: "text", text: `Hello, ${name}!` }]
    };
  }
});

// 서버 시작
const transport = new StdioServerTransport();
await server.connect(transport);

OpenClaw에서 설정합니다:

{
  mcp: {
    servers: {
      "my-custom": {
        command: "node",
        args: ["/path/to/my-mcp-server.js"]
      }
    }
  }
}

MCP Server 디버깅

MCP 도구 목록 확인

# 로드된 모든 MCP 도구 확인
openclaw doctor

출력에 연결된 모든 MCP Server와 제공되는 도구가 나열됩니다.

MCP 디버그 로그 활성화

# MCP 통신 상세 정보 확인
openclaw logs --level debug

로그에 MCP 도구 호출의 요청과 응답이 표시됩니다:

[DEBUG] MCP tool call: filesystem.read_file({path: "/home/user/notes.txt"})
[DEBUG] MCP tool result: {content: [{type: "text", text: "file contents..."}]}

MCP Server 독립 테스트

MCP Inspector 도구를 사용하여 MCP Server를 독립적으로 테스트할 수 있습니다:

npx @modelcontextprotocol/inspector npx -y @modelcontextprotocol/server-filesystem --allow-read /tmp

이 명령은 MCP 도구를 직접 호출하고 테스트할 수 있는 웹 인터페이스를 엽니다.

보안 모범 사례

최소 권한 원칙

{
  mcp: {
    servers: {
      "filesystem": {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-filesystem",
               "--allow-read",           // 읽기 전용
               "/home/user/public-docs"  // 디렉토리 제한
        ]
        // 주의: --allow-write를 추가하지 않음
      }
    }
  }
}

API 키 보안

설정 파일에 API 키를 하드코딩하지 말고 환경 변수를 사용하십시오:

{
  mcp: {
    servers: {
      "github": {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-github"],
        env: {
          // 시스템 환경 변수 참조
          GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_TOKEN}"
        }
      }
    }
  }
}

그런 다음 시스템에서 환경 변수를 설정합니다:

export GITHUB_TOKEN="ghp_xxxxx"

네트워크 격리

원격 MCP Server(SSE 모드)의 경우 다음을 권장합니다:

  • HTTPS 연결 사용
  • 인증 Token 설정
  • 접근 가능한 IP 범위 제한

자주 묻는 질문

MCP Server 시작 실패

# npx가 정상적으로 실행되는지 확인
npx -y @modelcontextprotocol/server-filesystem --help

# Node.js 버전 확인
node --version  # 22+ 필요

도구 호출 타임아웃

일부 MCP 도구(예: HTTP 요청)는 네트워크 문제로 타임아웃될 수 있습니다. 설정에서 타임아웃 시간을 설정할 수 있습니다:

{
  mcp: {
    // 전역 타임아웃 설정 (밀리초)
    timeout: 30000,
    servers: {
      "http-fetch": {
        command: "npx",
        args: ["-y", "@openclaw-mcp/http-fetch"],
        // 이 Server에 대한 개별 타임아웃 설정
        timeout: 60000
      }
    }
  }
}

AI가 예상 도구를 호출하지 않는 경우

Skill에서 mcp_tools가 올바르게 선언되었는지, MCP Server 이름이 설정과 일치하는지 확인하십시오. 디버그 로그를 확인하여 도구가 올바르게 로드되었는지 확인합니다.

마무리

MCP는 OpenClaw 기능 확장의 기반입니다. 다양한 MCP Server를 설정함으로써 AI 어시스턴트가 파일 시스템 접근, 데이터베이스 조회, API 호출, GitHub 조작 등 거의 모든 외부 리소스에 접근할 수 있게 됩니다. MCP의 작동 원리와 설정 방법을 이해하면 더 강력한 Skill과 자동화 워크플로우를 구축하는 데 도움이 됩니다.

OpenClaw는 무료 오픈소스 개인 AI 어시스턴트로, WhatsApp, Telegram, Discord 등 다양한 플랫폼을 지원합니다
더 많은 튜토리얼 Skills 다운로드

관련 튜토리얼

OpenClaw 커스텀 Skill 개발 방법
OpenClaw 도구 체인 처리 파이프라인 상세 설명
OpenClaw 시스템 프롬프트 커스터마이징 및 동적 구성