Oct 11, 2025

MCP 로컬 파일 접근 완벽 가이드

MCP란 무엇인가?

Model Context Protocol(MCP)은 Anthropic이 개발한 오픈 표준 프로토콜로, AI 모델이 다양한 데이터 소스와 안전하게 상호작용할 수 있도록 설계되었습니다. 특히 로컬 파일 시스템, 데이터베이스, API 등 외부 리소스에 접근할 때 표준화된 방식을 제공합니다.

MCP의 핵심 가치는 보안, 확장성, 표준화입니다. AI 애플리케이션이 로컬 파일에 접근할 때 무분별한 접근을 방지하고, 사용자가 명시적으로 허용한 범위 내에서만 동작하도록 보장합니다.

MCP 서버와 클라이언트 아키텍처

MCP는 클라이언트-서버 아키텍처를 기반으로 동작합니다:

MCP 서버

MCP 서버는 실제 리소스(파일 시스템, 데이터베이스 등)에 접근하는 역할을 담당합니다. 서버는 다음과 같은 기능을 제공합니다:

도구(Tools): AI가 호출할 수 있는 함수들 (예: 파일 읽기, 쓰기, 검색)
리소스(Resources): AI가 접근할 수 있는 데이터 소스
프롬프트(Prompts): 미리 정의된 프롬프트 템플릿

MCP 클라이언트

MCP 클라이언트는 AI 애플리케이션(Claude Desktop, IDEs 등)에 내장되어 서버와 통신합니다. 사용자의 요청을 받아 적절한 MCP 서버에 전달하고 결과를 받아옵니다.

로컬 파일 시스템 MCP 서버 설정하기

로컬 파일에 접근하기 위해서는 MCP 파일 시스템 서버를 설정해야 합니다. 다음은 단계별 가이드입니다.

1. MCP 파일 시스템 서버 설치

먼저 공식 MCP 파일 시스템 서버를 설치합니다:

npm install -g @modelcontextprotocol/server-filesystem

또는 특정 프로젝트에서 사용하려면:

npm install --save-dev @modelcontextprotocol/server-filesystem

2. MCP 설정 파일 구성

Claude Desktop 또는 다른 MCP 클라이언트를 사용하는 경우, 설정 파일을 작성해야 합니다. 일반적으로 ~/.config/claude/mcp.json 또는 프로젝트 루트의 mcp.json 파일에 다음과 같이 작성합니다:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Documents/my-project"
      ]
    }
  }
}

위 설정에서 /Users/username/Documents/my-project는 AI가 접근할 수 있는 루트 디렉토리입니다. 보안상 중요: 이 경로 밖의 파일에는 접근할 수 없습니다.

3. 여러 디렉토리 허용하기

여러 디렉토리에 접근해야 하는 경우, 각각을 별도의 서버로 등록하거나 여러 경로를 인자로 전달할 수 있습니다:

{
  "mcpServers": {
    "project-files": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Documents/project-a",
        "/Users/username/Documents/project-b"
      ]
    },
    "documents": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Documents"
      ]
    }
  }
}

MCP를 통한 파일 작업

MCP 파일 시스템 서버가 설정되면, AI는 다음과 같은 작업을 수행할 수 있습니다:

파일 읽기

AI에게 다음과 같이 요청할 수 있습니다:

"프로젝트의 package.json 파일을 읽어줘"

MCP 서버는 허용된 디렉토리 내에서 해당 파일을 찾아 내용을 반환합니다. 내부적으로는 read_file 도구가 호출됩니다.

파일 쓰기

새 파일을 생성하거나 기존 파일을 수정할 수 있습니다:

"src/components 폴더에 Button.tsx 파일을 생성하고,
React 버튼 컴포넌트를 작성해줘"

MCP는 write_file 도구를 사용하여 파일을 안전하게 생성합니다.

디렉토리 탐색

디렉토리 구조를 확인할 수 있습니다:

"현재 프로젝트의 src 폴더 구조를 보여줘"

list_directory 도구가 호출되어 디렉토리 내용을 반환합니다.

파일 검색

특정 패턴이나 내용을 가진 파일을 검색할 수 있습니다:

"프로젝트에서 'useState'를 사용하는 모든 파일을 찾아줘"

search_files 도구가 grep 또는 ripgrep을 사용하여 파일을 검색합니다.

고급 MCP 활용 사례

1. 프로젝트 분석 자동화

MCP를 활용하면 전체 코드베이스를 분석하고 리포트를 생성할 수 있습니다:

"프로젝트의 모든 TypeScript 파일을 분석하고,
타입 안정성 개선이 필요한 부분을 리포트로 작성해줘"

AI는 MCP를 통해 여러 파일을 읽고, 분석하고, 결과를 새 파일로 저장할 수 있습니다.

2. 코드 리팩토링

대규모 리팩토링 작업도 MCP를 통해 안전하게 수행할 수 있습니다:

"모든 컴포넌트 파일에서 구 버전의 훅 사용법을
새 버전으로 마이그레이션해줘"

AI는 파일을 읽고, 패턴을 찾고, 변경 사항을 적용한 후 파일을 업데이트합니다.

3. 문서 생성

코드로부터 자동으로 문서를 생성할 수 있습니다:

"각 API 엔드포인트 파일을 읽고 OpenAPI 명세를 생성해줘"

4. 테스트 코드 작성

기존 코드를 분석하여 테스트를 자동 생성할 수 있습니다:

"utils 폴더의 모든 함수에 대한 단위 테스트를 작성해줘"

MCP 보안 모범 사례

로컬 파일 시스템에 접근할 때는 보안이 매우 중요합니다. 다음 모범 사례를 따르세요:

1. 최소 권한 원칙

AI가 접근해야 하는 최소한의 디렉토리만 허용하세요. 전체 홈 디렉토리나 시스템 루트를 허용하지 마세요.

좋은 예:

{
  "mcpServers": {
    "project": {
      "args": ["/Users/username/projects/my-app"]
    }
  }
}

나쁜 예:

{
  "mcpServers": {
    "all-files": {
      "args": ["/Users/username"]  // 너무 광범위함
    }
  }
}

2. 민감한 정보 제외

.env 파일, SSH 키, 인증서 등이 포함된 디렉토리는 제외하세요. .gitignore 패턴을 활용하여 특정 파일을 제외할 수 있습니다.

3. 읽기 전용 모드 사용

분석이나 검색만 필요한 경우, 읽기 전용 모드로 MCP 서버를 실행하세요:

{
  "mcpServers": {
    "readonly-docs": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "--readonly",
        "/Users/username/Documents"
      ]
    }
  }
}

4. 로그 모니터링

MCP 서버는 모든 파일 접근 요청을 로그로 남깁니다. 주기적으로 로그를 검토하여 의심스러운 활동이 없는지 확인하세요.

5. 버전 관리와 함께 사용

파일 수정 작업을 할 때는 항상 Git과 같은 버전 관리 시스템을 사용하여 변경 사항을 추적하고 필요시 롤백할 수 있도록 하세요.

커스텀 MCP 서버 만들기

기본 파일 시스템 서버로 충분하지 않다면, 직접 MCP 서버를 만들 수 있습니다. TypeScript 예제:

import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import fs from 'fs/promises';
import path from 'path';

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

// 파일 읽기 도구 정의
server.setRequestHandler('tools/list', async () => {
  return {
    tools: [
      {
        name: 'read_project_file',
        description: '프로젝트 파일을 읽습니다',
        inputSchema: {
          type: 'object',
          properties: {
            path: {
              type: 'string',
              description: '읽을 파일의 경로',
            },
          },
          required: ['path'],
        },
      },
    ],
  };
});

// 도구 호출 핸들러
server.setRequestHandler('tools/call', async (request) => {
  if (request.params.name === 'read_project_file') {
    const filePath = request.params.arguments?.path as string;
    const allowedDir = '/Users/username/projects';

    // 경로 검증
    const fullPath = path.resolve(allowedDir, filePath);
    if (!fullPath.startsWith(allowedDir)) {
      throw new Error('접근 권한이 없는 경로입니다');
    }

    const content = await fs.readFile(fullPath, 'utf-8');
    return {
      content: [
        {
          type: 'text',
          text: content,
        },
      ],
    };
  }

  throw new Error('알 수 없는 도구입니다');
});

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

이렇게 만든 커스텀 서버는 특정 비즈니스 로직, 추가 검증, 또는 다른 데이터 소스와의 통합을 포함할 수 있습니다.

MCP vs 전통적인 파일 접근 방식

전통적인 방식의 문제점

AI가 파일 시스템에 직접 접근하면 보안 위험이 큼
접근 권한을 세밀하게 제어하기 어려움
표준화된 프로토콜이 없어 각 AI 도구마다 다른 방식 사용
감사(audit) 및 로깅이 어려움

MCP의 장점

표준화: 모든 MCP 호환 클라이언트에서 동일하게 작동
보안: 명시적으로 허용된 경로만 접근 가능
투명성: 모든 작업이 로그로 기록됨
확장성: 커스텀 도구를 쉽게 추가 가능
격리: 각 MCP 서버는 독립적인 프로세스로 실행되어 격리됨

실전 활용 팁

1. 프로젝트별 MCP 설정

각 프로젝트마다 .mcp/config.json 파일을 만들어 프로젝트별 설정을 관리하세요:

{
  "mcpServers": {
    "this-project": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "."
      ]
    }
  }
}

2. 환경 변수 활용

경로를 하드코딩하지 말고 환경 변수를 사용하세요:

{
  "mcpServers": {
    "workspace": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "${WORKSPACE_DIR}"
      ],
      "env": {
        "WORKSPACE_DIR": "/Users/username/workspace"
      }
    }
  }
}

3. 파일 패턴 필터링

특정 파일 타입만 접근하도록 제한할 수 있습니다:

{
  "mcpServers": {
    "source-only": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "--include",
        "*.ts,*.tsx,*.js,*.jsx",
        "/Users/username/project/src"
      ]
    }
  }
}

문제 해결 가이드

MCP 서버가 시작되지 않을 때

권한 확인: 디렉토리 읽기/쓰기 권한이 있는지 확인
경로 확인: 절대 경로를 사용하고 있는지 확인
로그 확인: MCP 클라이언트의 로그를 확인하여 오류 메시지 파악

파일을 찾을 수 없다는 오류

경로가 허용된 디렉토리 내에 있는지 확인
대소문자 구분: macOS는 기본적으로 대소문자를 구분하지 않지만, Linux는 구분
심볼릭 링크: 심볼릭 링크가 허용된 경로 밖을 가리키는지 확인

성능 문제

대용량 파일: 매우 큰 파일은 청크 단위로 읽기
파일 개수: 한 번에 너무 많은 파일을 처리하지 말고 배치로 나누기
캐싱: 자주 접근하는 파일은 클라이언트 측에서 캐싱 고려

마무리

MCP를 통한 로컬 파일 접근은 AI 애플리케이션의 가능성을 크게 확장합니다. 보안을 유지하면서도 AI가 실제 작업을 수행할 수 있게 하는 강력한 도구입니다.

핵심 포인트:

MCP는 표준화되고 안전한 파일 접근 방식을 제공합니다
최소 권한 원칙을 항상 따르세요
커스텀 MCP 서버로 특수한 요구사항을 충족할 수 있습니다
로그와 모니터링을 통해 보안을 유지하세요

MCP를 올바르게 활용하면 AI 어시스턴트가 진정한 개발 파트너가 될 수 있습니다. 코드 작성, 리팩토링, 문서화, 테스트 등 다양한 작업을 안전하고 효율적으로 수행할 수 있습니다.