SSD Nodes Learn Hosting plans →
가이드 Matt Connor작성자 Matt Connor

Claude Desktop 설정 파일에 MCP 서버 추가하기

Windows, macOS, Linux의 claude_desktop_config.json 경로와 mcpServers 블록 작성법, 앱 재시작, 그리고 '항상 허용' 버튼이 실제로 무엇을 허가하는지 정리했습니다.

Claude Desktop 설정 파일은 어디에 있나

Claude Desktop 설정 파일의 이름은 claude_desktop_config.json이고, 경로는 운영체제마다 다릅니다. Windows는 %APPDATA%\Claude\claude_desktop_config.json, macOS는 ~/Library/Application Support/Claude/claude_desktop_config.json입니다. 이 두 값은 Anthropic의 MCP 문서에 그대로 적혀 있는 경로입니다. 이 파일에 mcpServers 블록을 적으면 앱이 켜질 때 그 서버를 띄웁니다.

MCP(model context protocol, 모델 컨텍스트 프로토콜)는 모델이 쓸 도구와 데이터를 외부 프로그램이 노출하는 규격입니다. 서버가 붙는 방식은 두 가지입니다. 하나는 내 컴퓨터에서 stdio(표준 입출력)로 대화하는 로컬 프로세스이고, 다른 하나는 원격 주소에 HTTP로 연결하는 서버입니다. 설정 파일이 주로 담당하는 쪽은 앞의 로컬 프로세스입니다. 원격 서버는 앱 UI에서 붙이는 길이 따로 있고, 아래에서 둘 다 다룹니다.

경로를 손으로 찾기보다 앱이 열어주게 하는 편이 낫습니다. 왼쪽 위 메뉴에서 Settings를 열고(단축키 Ctrl+,), 사이드바의 Developer 탭에서 Edit Config를 누릅니다. 파일이 없으면 만들어 주고, 있으면 기본 편집기로 엽니다. 다만 Windows에서는 이 버튼이 앱이 실제로 읽는 파일과 다른 파일을 여는 사례가 보고되어 있습니다. 아래에 절을 따로 두었습니다.

Linux는 사정이 조금 다릅니다. MCP 문서의 경로 목록에는 macOS와 Windows만 있습니다. 대신 Anthropic의 관리자 설정 문서가 Linux 로그 파일을 ~/.config/Claude/logs/main.log로 명시하므로, 앱 데이터 디렉터리는 ~/.config/Claude입니다. 그 안의 claude_desktop_config.json을 쓰는 것이 일반적인 관행이지만 공식 문서에 적힌 값은 아닙니다. 그래서 Linux에서는 Edit Config가 실제로 만든 파일을 먼저 확인하고 그 파일을 편집하십시오. 추측한 경로에 파일을 만들면 앱은 그 파일을 읽지 않고, 오류도 남기지 않습니다.

설정 파일과 스킬 폴더는 서로 다른 장치입니다. 이 파일은 서버 프로세스를 띄우는 일만 하고, 모델의 행동 지침을 담지 않습니다. 둘의 역할 구분은 스킬과 MCP와 규칙 파일이 각각 담당하는 범위에서 따로 다룹니다.

공식 빌드는 어느 운영체제까지 있나

2026년 9월 기준 Anthropic은 macOS, Windows, Linux용 Claude Desktop을 배포합니다. Linux 빌드는 베타입니다. 최소 요구 사항은 macOS 11 이상, Windows 10 이상, Ubuntu 22.04 LTS 또는 Debian 12 이상이고 x64와 arm64를 지원합니다.

Linux에서는 apt 저장소를 쓰는 쪽이 권장됩니다. .deb 파일을 직접 내려받아 설치하면 이후 자동 업데이트를 받지 못합니다.

sudo curl -fsSLo /usr/share/keyrings/claude-desktop-archive-keyring.asc https://downloads.claude.ai/claude-desktop/key.asc
echo "deb [signed-by=/usr/share/keyrings/claude-desktop-archive-keyring.asc] https://downloads.claude.ai/claude-desktop/apt/stable stable main" | sudo tee /etc/apt/sources.list.d/claude-desktop.list
sudo apt update && sudo apt install claude-desktop

Linux 베타에는 빠진 기능이 있습니다. 컴퓨터 사용(computer use)과 음성 입력이 없고, 전역 단축키인 Quick Entry는 Wayland에서 제한적으로 동작합니다. MCP 서버 설정 자체는 세 운영체제에서 같은 모양입니다.

문서가 서로 다른 말을 하는 지점이 하나 있습니다. MCP 사이트의 로컬 서버 안내문은 여전히 Claude Desktop이 macOS와 Windows용이라고 적고 있습니다. Anthropic 지원 문서의 설치 안내는 Linux 베타 빌드와 apt 저장소를 설명합니다. 설치 가능 여부에 관해서는 지원 문서 쪽이 최신입니다.

mcpServers 블록은 어떤 모양인가

설정 파일의 최상위 키는 mcpServers입니다. 그 아래에 서버 이름을 키로 하는 객체를 하나씩 넣습니다. 서버 이름은 앱 안에서 그대로 보이는 이름입니다.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "C:\\Users\\username\\Desktop",
        "C:\\Users\\username\\Downloads"
      ]
    }
  }
}

각 키의 뜻은 이렇습니다. command는 실행할 프로그램이고, args는 그 프로그램에 넘길 인자 배열입니다. 위 예시의 -y는 패키지 설치 확인을 자동으로 승인하는 플래그이고, 그 뒤의 경로들은 이 서버가 접근을 허용받는 디렉터리입니다. 서버에 환경 변수를 넘겨야 하면 같은 수준에 env 객체를 추가합니다.

macOS와 Linux에서는 같은 설정이 이렇게 됩니다.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Desktop",
        "/Users/username/Downloads"
      ],
      "env": {
        "SOME_TOKEN": "..."
      }
    }
  }
}

Windows 경로는 JSON 문자열 안에서 역슬래시를 두 번 씁니다. C:\Users는 JSON에서 C:\\Users가 됩니다. 역슬래시를 하나만 쓰면 \U가 잘못된 이스케이프로 해석되어 파일 전체가 파싱에 실패합니다. 파일이 깨지면 그 안의 서버가 전부 사라지므로, 서버 하나를 잘못 적었는데 모든 서버가 없어진 것처럼 보입니다.

경로는 반드시 절대 경로여야 합니다. 상대 경로는 앱이 서버를 띄운 작업 디렉터리를 기준으로 해석되고, 그 디렉터리는 사용자가 생각하는 위치가 아닙니다. 그리고 npx를 쓰는 서버는 전부 Node.js 런타임에 의존하므로, 터미널에서 node --version이 버전을 출력하는지 먼저 확인하십시오.

새로 추가한 서버를 앱이 인식하게 하려면

설정 파일을 저장한 다음 앱을 완전히 종료하고 다시 켜야 합니다. 창을 닫는 것으로는 부족합니다. macOS에서는 창을 닫아도 프로세스가 남고, Windows에서는 트레이에 남습니다. 앱은 실행 시점에 설정 파일을 읽고 그때 서버 프로세스를 띄우기 때문에, 프로세스가 살아 있으면 새 설정은 읽히지 않습니다.

다시 켠 뒤 확인하는 위치는 대화 입력창 왼쪽 아래의 추가 버튼입니다. 버튼을 누르고 Connectors 위에 마우스를 올린 다음 Manage connectors를 열면 연결된 서버 목록이 나옵니다. 서버를 누르면 그 서버가 노출한 도구 목록이 보입니다. 목록에 서버가 없으면 설정이 읽히지 않았거나 서버가 시작에 실패한 것입니다.

확인하는 순서는 이렇습니다.

  1. JSON 문법을 검사합니다. 마지막 쉼표 하나가 남아 있어도 파일 전체가 무효가 됩니다.
  2. args의 경로가 절대 경로이고 실제로 존재하는지 확인합니다.
  3. 같은 명령을 터미널에서 직접 실행해 봅니다. 앱 밖에서 실패하는 명령은 앱 안에서도 실패합니다.
  4. 로그를 읽습니다.
npx -y @modelcontextprotocol/server-filesystem /Users/username/Desktop

로그 위치는 macOS가 ~/Library/Logs/Claude, Windows가 %APPDATA%\Claude\logs입니다. mcp.log에는 연결과 연결 실패에 관한 일반 기록이 남습니다. mcp-server-<서버이름>.log에는 그 서버가 표준 오류로 내보낸 출력이 그대로 남습니다. stdio 서버는 모든 로그를 표준 오류로 보내는 경우가 많으니, 이 파일이 오류만 담고 있다고 생각하지 마십시오.

tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

Windows에서는 이렇게 읽습니다.

type "%APPDATA%\Claude\logs\mcp*.log"

Windows에서 Edit Config가 다른 파일을 여는 문제

Windows에서 MSIX 패키지로 설치한 경우, Edit Config 버튼이 여는 파일과 앱이 읽는 파일이 다를 수 있습니다. 버튼은 C:\Users\<사용자>\AppData\Roaming\Claude\claude_desktop_config.json을 엽니다. 그런데 앱이 읽는 파일은 다음 경로입니다.

%LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json

원인은 이렇습니다. MSIX 파일 시스템 가상화는 앱이 %APPDATA%\Claude\를 읽을 때 그 요청을 위 가상화 경로로 돌립니다. 그런데 Edit Config가 쓰는 Electron의 shell.openPath()는 이 리다이렉션을 거치지 않고 실제 경로를 엽니다. 그래서 문서대로 편집했는데도 서버가 조용히 로드되지 않습니다. 오류 메시지가 없고, 기대한 위치에 로그도 생기지 않으며, Developer 설정에도 설정이 읽히지 않았다는 표시가 없습니다.

2026년 9월 기준 이 문제는 공개된 버그 보고 상태이고 해결이 확인되지 않았습니다. 서버가 목록에 나타나지 않고 로그도 비어 있으면 가상화 경로에 파일이 있는지 확인하고, 있다면 그쪽을 편집하십시오. 두 파일이 모두 존재할 때 앱이 읽는 쪽은 가상화 경로입니다.

Windows에서 ENOENT 오류와 APPDATA 경로

서버가 로드에 실패하고 로그의 경로 안에 ${APPDATA}가 펼쳐지지 않은 채 찍힌 ENOENT 오류가 보이면, 그 환경 변수가 전달되지 않은 것입니다. 해결은 env에 APPDATA 값을 직접 넣는 것입니다.

{
  "mcpServers": {
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "APPDATA": "C:\\Users\\user\\AppData\\Roaming\\",
        "BRAVE_API_KEY": "..."
      }
    }
  }
}

넣은 뒤 앱을 다시 켭니다. 그래도 npx가 실패하면 npm이 전역으로 설치되지 않은 경우입니다. 전역 설치가 되어 있으면 %APPDATA%\npm 디렉터리가 존재합니다. 없으면 npm install -g npm으로 설치하십시오.

서버를 여러 개 둘 때

mcpServers 아래에 서버를 여러 개 적으면 앱은 켜질 때 그 전부를 띄웁니다. 서버가 늘어나면 앱 시작이 느려지고, 하나가 시작에 실패해도 나머지는 정상으로 보이므로 실패가 눈에 잘 띄지 않습니다. 그래서 서버 이름을 대화에서 알아볼 수 있게 짓는 것이 실제로 도움이 됩니다. server1보다 vps-notes나 work-jira가 낫습니다. Manage connectors 목록과 로그 파일 이름에 그 이름이 그대로 쓰이기 때문입니다.

파일을 고치기 전에 복사본을 만들어 두십시오. JSON 문법이 깨지면 앱은 파일 전체를 읽지 못하고, 서버 하나의 실수가 서버 전부를 사라지게 합니다. JSON에는 주석 문법이 없으므로 서버를 잠시 끄고 싶다면 블록을 주석 처리할 수 없습니다. 파일을 복사해 두고 블록을 지우는 방식으로 작업하십시오.

'항상 허용' 버튼은 무엇을 허가하는가

승인 창은 서버 단위가 아니라 도구 단위로 뜹니다. 서버 하나가 도구 열 개를 노출하면 창도 도구별로 따로 뜹니다. 한 번만 허용하면 지금 그 호출에만 적용되고, 같은 도구를 다시 호출하면 창이 또 뜹니다. '항상 허용'(Allow always)을 누르면 그 도구는 다음부터 확인을 거치지 않고 실행됩니다.

Anthropic 문서가 이 버튼에 붙인 조건은 분명합니다. 감독 없이 실행되어도 괜찮다고 판단한 서버와 도구에만 '항상 허용'을 누르라는 것입니다. 이 문장을 뒤집으면 버튼의 의미가 나옵니다. 이 버튼은 그 도구를 앞으로 사람 확인 없이 실행한다는 허가입니다.

여기에 문서가 함께 경고하는 위험이 있습니다. 서버 개발자가 도구의 동작을 예고 없이 바꿀 수 있습니다. 승인 창이 사라진 뒤에는 바뀐 동작도 묻지 않고 실행됩니다. 즉 '항상 허용'은 오늘 읽은 도구 설명에 대한 허가가 아니라, 그 이름을 가진 도구에 대한 허가입니다.

허가가 남는 범위는 공식 문서에 명시되어 있지 않습니다. 지금 대화에만 남는지 계정 전체에 남는지 문서가 밝히지 않으므로, 넓은 쪽을 가정하는 것이 안전합니다. 파일을 지우는 도구와 메일을 보내는 도구에는 누르지 마십시오. 되돌리는 곳은 승인 창이 아니라 Settings의 Connectors입니다. 서버를 열면 도구를 개별로 켜고 끌 수 있고, 로컬 서버라면 설정 파일에서 서버 블록을 지우고 앱을 다시 켜는 것이 가장 확실합니다. 승인 단계를 설계 요소로 다루는 관점은 에이전트의 동작을 승인 게이트로 감싸는 방법에 정리했습니다.

npx 패키지와 내가 운영하는 서버는 다른 신뢰 판단이다

"command": "npx"에 -y와 패키지 이름만 적는 설정의 뜻은, 앱을 켤 때마다 레지스트리에서 그 패키지를 가져와 실행한다는 것입니다. 버전을 고정하지 않으면 어제 검토한 코드와 오늘 실행되는 코드가 다를 수 있습니다. 최소한 패키지@버전 형태로 버전을 못 박으십시오.

그리고 이 프로세스는 승인 창보다 먼저 시작됩니다. 앱은 실행 시점에 설정 파일의 서버를 모두 띄웁니다. 도구 승인 창은 모델이 도구를 호출할 때 뜨는 것이고, 프로세스가 켜지는 것 자체를 막지 않습니다. 게다가 Anthropic 문서의 표현대로 서버는 사용자 계정 권한으로 돌기 때문에, 사용자가 손으로 할 수 있는 파일 작업을 모두 할 수 있습니다. ~/.ssh의 개인키, 브라우저 프로필, 클라우드 자격 증명, 작업 중인 소스 코드가 같은 권한 안에 있습니다.

내 VPS에 올린 서버는 다른 판단이 됩니다. 코드를 내가 배포했고, 버전이 언제 바뀌는지 내가 알고, 그 프로세스가 건드릴 수 있는 파일은 랩톱이 아니라 서버의 한 사용자 계정 범위입니다. 랩톱이 열어 주는 것은 HTTPS 연결 하나뿐입니다.

그래도 남는 위험이 있습니다. Anthropic 문서가 경고하는 대로, 악의적인 MCP 서버는 응답 안에 숨은 지시를 넣어 모델이 의도하지 않은 동작을 하게 만들 수 있습니다. 서버가 내 것이어도 그 서버가 읽어 오는 데이터는 내 것이 아닐 수 있습니다. 도구의 입력과 출력을 확인하는 습관이 필요하고, 이 경로가 어떻게 작동하는지는 에이전트가 읽는 데이터를 통해 오염되는 방식에서 더 자세히 다룹니다.

랩톱마다 프로세스를 띄우지 않고 VPS의 서버에 붙이기

로컬 stdio 방식은 기기 수만큼 복제됩니다. 노트북과 데스크톱을 함께 쓰면 Node.js 런타임, 패키지 버전, API 키, 설정 파일이 두 벌이 됩니다. 키를 회전하면 두 곳을 고쳐야 하고, 한 곳만 고치면 그 기기에서만 조용히 실패합니다. 서버가 파일이나 데이터베이스를 들고 있으면 데이터도 두 벌이 됩니다.

서버를 VPS 한 대에 올리고 원격 전송으로 붙이면 이 복제가 없어집니다. 서버 쪽을 세우는 일, 즉 HTTP 전송, 리버스 프록시, TLS(전송 계층 보안) 인증서, 인증은 VPS에서 MCP 서버를 직접 운영하는 방법에서 다룹니다. 여러 기기가 같은 서버에 붙을 때 세션 상태를 서버에 두지 않는 설계가 왜 편한지는 상태를 두지 않는 MCP 서버가 무엇을 뜻하는지를 보십시오. 여기서는 클라이언트 쪽만 적습니다.

붙이는 길은 두 가지입니다.

첫째, Custom connector입니다. Settings에서 Connectors를 열고 오른쪽 위 Add 버튼을 누른 다음 Add custom connector를 고릅니다. 서버의 전체 URL을 넣습니다. https://와 경로까지 포함한 주소여야 합니다. 서버가 인증을 요구하면 OAuth 흐름이 진행되고, 끝나면 그 서버의 도구와 리소스를 대화에서 쓸 수 있습니다. 연결한 뒤 Connectors에서 그 서버를 다시 열면 도구를 개별로 켜고 끌 수 있습니다. 설정 파일을 건드리지 않고, 기기를 바꿔도 같은 계정에서 그대로 쓰입니다.

둘째, mcp-remote 브리지입니다. 설정 파일 쪽에서 원격 서버를 관리하고 싶을 때, 또는 커넥터 UI가 넣어 주지 않는 헤더를 붙여야 할 때 씁니다. 이 패키지는 앱과는 stdio로 이야기하고 바깥으로는 HTTP 또는 SSE로 원격 서버에 연결합니다.

{
  "mcpServers": {
    "vps-notes": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.example.com/mcp",
        "--transport",
        "http-only"
      ]
    }
  }
}

--transport의 기본값은 http-first입니다. HTTP를 먼저 시도하고 404로 실패하면 SSE로 내려갑니다. sse-first는 반대 방향이며 SSE가 405로 실패하면 HTTP를 씁니다. 서버가 어느 쪽을 지원하는지 알고 있다면 http-only나 sse-only로 못 박는 편이 낫습니다. 폴백이 없으면 실패가 첫 시도에서 드러나고, 원인을 찾을 때 읽을 로그가 절반으로 줄어듭니다.

헤더로 토큰을 보내야 하면 값을 인자에 직접 쓰지 말고 환경 변수를 쓰십시오.

{
  "mcpServers": {
    "vps-notes": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.example.com/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer 여기에토큰"
      }
    }
  }
}

Authorization:${AUTH_HEADER}에 공백이 없는 것은 의도된 형태입니다. mcp-remote 문서에 따르면 Windows의 Claude Desktop과 일부 클라이언트는 args 안의 공백을 이스케이프하지 않고 npx를 호출하는 버그가 있어서, 공백이 든 값이 깨집니다. 값을 env로 빼면 이 문제를 피하고, 토큰이 프로세스 인자 목록에 남지 않는 이점도 같이 얻습니다. 같은 기기의 다른 사용자가 프로세스 목록에서 인자를 읽을 수 있기 때문입니다.

주소는 HTTPS로 두십시오. 사설망 안에서 평문 HTTP가 필요하면 --allow-http 플래그가 있지만, 문서가 명시하듯 트래픽을 가로챌 수 없는 안전한 사설망에서만 쓸 것입니다. 공용 인터넷을 지나는 연결에는 쓰지 마십시오.

인증이 계속 실패하면 캐시된 자격 증명을 지웁니다. mcp-remote는 자격 증명을 ~/.mcp-auth에 저장합니다. 위치는 MCP_REMOTE_CONFIG_DIR로 바꿀 수 있습니다. rm -rf ~/.mcp-auth를 실행하고 앱을 다시 켜면 인증 흐름이 처음부터 진행됩니다.

어디까지가 클라이언트의 일인가

이 글이 다룬 범위는 클라이언트 쪽입니다. 파일 경로, mcpServers 블록, 앱 재시작, 로그 위치, 승인 버튼의 의미까지입니다. 서버가 실제로 무엇을 노출하고 누가 그것을 호출할 수 있는지는 서버 쪽 결정이고, 그 절반은 MCP 서버를 VPS에 올리는 쪽에 있습니다. 랩톱의 설정 파일에는 언제든 다시 발급할 수 있는 비밀만 두고, 되돌리기 어려운 권한은 서버에서 관리하십시오. 랩톱은 잃어버릴 수 있고, 설정 파일은 평문입니다.

FAQ

Claude Desktop 설정 파일은 정확히 어디에 있나요?

파일 이름은 claude_desktop_config.json입니다. Windows는 %APPDATA%\Claude\claude_desktop_config.json, macOS는 ~/Library/Application Support/Claude/claude_desktop_config.json이고 이 두 경로는 공식 MCP 문서에 적혀 있습니다. Linux 경로는 그 목록에 없습니다. Linux에서는 Settings의 Developer 탭에서 Edit Config를 눌러 앱이 만든 파일을 확인하고 그 파일을 편집하십시오. 앱 데이터 디렉터리는 ~/.config/Claude입니다.

설정 파일을 고쳤는데 서버가 나타나지 않습니다. 무엇을 확인해야 하나요?

먼저 앱을 창만 닫는 것이 아니라 완전히 종료하고 다시 켜십시오. 앱은 실행 시점에만 설정을 읽습니다. 그다음 JSON 문법을 검사하고, args의 경로가 절대 경로인지 확인하고, 같은 명령을 터미널에서 직접 실행해 보십시오. 그래도 목록에 없으면 로그를 읽습니다. macOS는 ~/Library/Logs/Claude, Windows는 %APPDATA%\Claude\logs이며 mcp.log와 서버별 로그 파일이 있습니다. Windows MSIX 설치에서는 Edit Config가 앱이 읽지 않는 파일을 여는 사례가 보고되어 있으니, %LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\ 아래도 확인하십시오.

'항상 허용'을 누르면 되돌릴 수 있나요?

되돌리는 위치는 승인 창이 아니라 Settings의 Connectors입니다. 해당 서버를 열면 도구를 개별로 끌 수 있습니다. 로컬 서버라면 설정 파일에서 서버 블록을 지우고 앱을 다시 켜는 방법이 가장 확실합니다. 이 허가가 현재 대화에만 남는지 계정 전체에 남는지는 공식 문서에 명시되지 않았으므로, 넓게 남는다고 가정하고 파일을 지우거나 메일을 보내는 도구에는 누르지 않는 편이 안전합니다.

원격 MCP 서버는 설정 파일에 URL만 적으면 되나요?

원격 서버를 붙이는 기본 경로는 설정 파일이 아니라 앱 UI입니다. Settings의 Connectors에서 Add를 누르고 Add custom connector를 골라 https://로 시작하는 전체 URL을 넣으면 됩니다. 설정 파일 쪽에서 관리하거나 직접 헤더를 붙여야 하면 mcp-remote를 command로 두고 URL을 args에 넣는 방식을 씁니다. 이때 토큰은 env로 빼십시오. args 안의 공백이 깨지는 버그를 피하고 프로세스 인자에 비밀이 남지 않습니다.

#claude-desktop#mcp#claude#ai-agents#vps