2강 실습 중심 ⏱ 약 60분

0. 학습 목표

→ 설정 파일을 직접 작성해 Claude Desktop에 MySQL MCP 서버를 연결하고, 연결 성공을 화면에서 확인합니다.

0.1 이번 글에서 다룰 내용

이번 글은 실습 중심 강의입니다.

1강에서 설치한 Claude Desktop에 이번에는 MySQL을 연결합니다. Claude가 MySQL에 직접 접속하는 것이 아니라, 중간에서 통역사 역할을 하는 MCP 서버를 실행하도록 설정 파일에 적어주는 작업입니다. 파일을 만들고, 접속 정보를 넣고, 앱을 재시작해 연결을 확인하는 순서로 진행합니다.

[화면 캡처: Claude Desktop에 MySQL 도구가 연결된 화면]

구분	내용
이해할 것	설정 파일의 역할, 환경변수로 접속 정보를 전달하는 방식
해볼 것	설정 파일 작성, 앱 완전 재시작, 도구 아이콘·대화로 연결 확인

1. Claude가 MySQL을 다루는 원리

→ 설정 파일의 역할과 MCP 구조, 자연어가 SQL로 실행되는 흐름을 먼저 이해합니다.

1.1 MCP — AI와 도구를 잇는 표준 규격

MCP(Model Context Protocol)는 AI가 외부 프로그램과 대화하는 공용 규격입니다.

MCP가 없던 시절에는 도구마다 전용 연동 코드를 따로 짜야 했습니다.

프린터마다 전용 케이블이 필요하던 것과 같습니다.

MCP는 USB-C 포트에 비유할 수 있습니다.

규격만 맞추면 MySQL이든 파일 시스템이든 같은 방식으로 꽂아 쓸 수 있습니다.

여기서 MCP 서버는 특정 도구(우리 경우 MySQL)를 AI가 쓸 수 있도록 감싸주는 통역사입니다.

Claude가 MySQL에 직접 접속하는 것이 아니라, 이 통역사를 거쳐서 명령을 주고받습니다.

1.2 Host · Client · Server 구조

MCP는 세 개의 역할로 구성됩니다.

이 중 우리가 직접 손대는 것은 Server 설정뿐이고, Client는 Claude Desktop이 알아서 처리합니다.

요소	정체	우리 실습에서는
Host	사용자와 대화하는 AI 앱 본체	Claude Desktop
Client	Host 안에서 연결을 담당하는 부분	자동 처리 (신경 쓸 필요 없음)
Server	도구를 감싼 통역사	MySQL MCP 서버 (npx로 실행)

채팅 프로그램에서 배운 Server(항상 대기하는 큰 프로그램)와는 다릅니다.

MCP Server는 Claude Desktop이 켜질 때 함께 실행되는 작은 프로그램입니다.

1.3 자연어가 SQL로 실행되는 흐름

"재고 5개 이하인 상품 보여줘"라고 입력하면 뒤에서 아래 순서가 일어납니다.

① 사용자 입력      "재고 5개 이하인 상품 보여줘"
② Claude(Host)    문장 해석 → MySQL 도구가 필요하다고 판단
③ Claude          SQL 생성 → SELECT * FROM products WHERE stock <= 5;
④ Client → Server MCP 규격으로 "이 쿼리 실행해줘" 전달
⑤ Server → MySQL  실제 SQL 실행
⑥ 결과 반환        MySQL → Server → Client → Claude
⑦ Claude          결과를 표·자연어로 정리해 응답

여기서 두 가지가 핵심입니다.

첫째, SQL을 만드는 건 Claude, 실행하는 건 Server로 역할이 나뉩니다.
둘째, Server는 허용된 작업만 실행합니다. 그래서 나중에 배울 읽기·쓰기 권한 설정이 Server 쪽에 있는 것입니다.

자연어로 말하더라도 그 뒤에서는 항상 SQL이 돈다는 점을 기억해두면,

Claude가 만든 SQL을 검증하는 눈이 곧 실무 역량이 됩니다.

1.4 설정 파일이 하는 일

그렇다면 Claude Desktop은 어떻게 이 MySQL 통역사를 실행할까요.

답은 설정 파일입니다.

Claude Desktop은 켜질 때 설정 파일을 먼저 읽고, 거기에 적힌 MCP 서버들을 자동으로 실행합니다.

우리가 적어줄 정보는 두 종류뿐입니다.

하나는 실행 방법(어떤 명령으로 통역사를 켤 것인가),
다른 하나는 접속 정보(통역사가 MySQL에 들어갈 때 쓸 주소와 계정)입니다.

접속 정보는 명령어에 직접 쓰지 않고 환경변수(env)에 적습니다.

환경변수는 프로그램에게 실행할 때 따로 건네주는 쪽지 같은 값으로, 여기에 적으면 해당 MCP 서버만 읽어 갑니다.

비밀번호를 코드 곳곳에 흩어 두지 않고 한곳에 모아 전달하는 방식이라고 이해하면 됩니다.

2. 설정 파일 작성하기

→ 설정 파일 위치를 찾아 MySQL MCP 서버 등록 내용을 입력합니다.

2.1 Node.js 설치하기

MySQL MCP 서버는 npx 명령으로 실행됩니다. npx는 Node.js에 함께 딸려 오므로, 설정 파일을 작성하기 전에 Node.js가 설치돼 있어야 합니다. 이게 없으면 나중에 앱 로그에 spawn npx ENOENT(npx를 찾지 못함) 오류가 납니다.

먼저 이미 설치돼 있는지 확인합니다. 터미널에서 아래를 실행해 경로와 버전이 나오면 이미 준비된 것이니 다음 소제목으로 넘어가면 됩니다.

which npx
node -v

아무것도 출력되지 않으면 Node.js가 없는 것입니다. 우분투에서 아래 명령으로 설치합니다.

sudo apt update
sudo apt install nodejs npm

설치가 끝나면 다시 node -v로 버전이 나오는지 확인합니다.

▶ 지금 해보세요

터미널에서 which npx와 node -v를 실행합니다.
경로·버전이 보이면 설치된 것이니 그대로 넘어갑니다.
아무것도 안 나오면 sudo apt install nodejs npm으로 설치한 뒤 node -v로 확인합니다.

💡 팁: which npx는 경로가 나오는데 앱에서만 spawn npx ENOENT가 난다면, nvm으로 설치한 경우일 수 있습니다. GUI 앱은 터미널 설정(.bashrc 등)을 읽지 않아 nvm 경로를 모르기 때문입니다. 이때는 설정 파일의 "command"에 npx 대신 which npx가 알려준 전체 경로를 그대로 적으면 해결됩니다.

apt로 설치되는 Node 버전이 낮으면 나중에 최신 LTS(nvm·NodeSource)로 올리는 게 좋지만, 지금은 동작 확인이 우선입니다.

2.2 Claude MCP 설정 파일 위치 찾기

[화면 캡처: Settings > Developer 탭의 Edit Config 버튼]

Claude Desktop 좌측 상단 메뉴에서 Settings > Developer 탭으로 이동하면 Edit Config 버튼이 있습니다.

이 버튼을 누르면 설정 파일이 있는 폴더가 열립니다. 파일을 직접 찾을 때의 경로는 운영체제별로 다릅니다.

OS	설정 파일 경로
Ubuntu	`~/.config/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`

우분투에서 파일이 아직 없다면 새로 만들면 됩니다. 아래처럼 폴더를 만들고 편집기로 파일을 여세요.

mkdir -p ~/.config/Claude
nano ~/.config/Claude/claude_desktop_config.json

💡 팁: ~/.config는 숨김 폴더입니다. 파일 관리자에서 직접 찾을 때는 Ctrl+H를 눌러 숨김 파일 표시를 켜세요. Windows는 탐색기 주소창에 %APPDATA%\Claude를 입력하면 바로 이동합니다.

2.2 MySQL MCP 서버 등록하기

설정 파일이 비어 있었다면 아래 내용을 그대로 작성합니다.

MySQL MCP 서버를 npx로 실행하고, 접속 정보를 env에 넣는 구조입니다.

{
  "mcpServers": {
    "mysql": {
      "command": "npx",
      "args": ["-y", "@benborla29/mcp-server-mysql"],
      "env": {
        "MYSQL_HOST": "127.0.0.1",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "root",
        "MYSQL_PASS": "1234",
        "MYSQL_DB": "inventory"
      }
    }
  }
}

항목	의미	주의점
"mysql"	이 서버의 별명 (자유 지정)	영문 권장
command + args	통역사 실행 명령	-y는 설치 질문 생략
MYSQL_HOST	DB 주소	내 PC이므로 127.0.0.1
MYSQL_PORT	DB의 문 번호	MySQL 기본값 3306
MYSQL_USER / PASS	접속 계정	본인 환경에 맞게 수정
MYSQL_DB	기본 사용 DB	3강에서 만들 inventory

nano로 작성했다면 Ctrl+O → Enter로 저장하고 Ctrl+X로 닫습니다.

▶ 지금 해보세요

터미널에서 mkdir -p ~/.config/Claude로 폴더를 만듭니다.
nano ~/.config/Claude/claude_desktop_config.json으로 파일을 엽니다.
위 내용을 붙여넣되 MYSQL_PASS·MYSQL_USER를 본인 환경에 맞게 고친 뒤 저장합니다.

2.3 파일에 이미 다른 내용이 있을 때

설정 파일이 비어 있었다면 2.2의 내용을 그대로 붙여넣으면 됩니다.

하지만 다른 MCP 서버를 이미 등록해 뒀다면 통째로 덮어쓰면 안 됩니다.

기존 mcpServers 안에 "mysql" 블록만 추가하는 방식으로 합쳐야 합니다.

예를 들어 이미 다른 서버가 있다면 아래처럼 나란히 두 개가 들어가는 형태가 됩니다.

{
  "mcpServers": {
    "other-server": {
      "command": "npx",
      "args": ["-y", "다른-mcp-서버"]
    },
    "mysql": {
      "command": "npx",
      "args": ["-y", "@benborla29/mcp-server-mysql"],
      "env": {
        "MYSQL_HOST": "127.0.0.1",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "root",
        "MYSQL_PASS": "1234",
        "MYSQL_DB": "inventory"
      }
    }
  }
}

다음을 참고하세요.

여기서 놓치기 쉬운 부분은 서버 블록 사이의 쉼표입니다. 위 예시에서 "other-server": { ... }가 끝나는 중괄호 뒤에 쉼표가 있어야 다음 "mysql" 블록과 이어집니다. 반대로 가장 마지막 블록 뒤에는 쉼표를 붙이지 않습니다.

💡 팁: JSON에서는 항목 사이에만 쉼표를 넣고, 마지막 항목 뒤에는 넣지 않습니다. 마지막에 붙는 쉼표(trailing comma)가 연결 실패의 가장 흔한 원인입니다.

작은따옴표(')가 아니라 반드시 큰따옴표(")를 사용하세요. 자신이 없으면 붙여넣은 내용을 jsonlint.com에 넣어 문법을 먼저 검사한 뒤 저장하는 것이 안전합니다.

▶ 지금 해보세요

파일에 이미 mcpServers 항목이 있는지 확인합니다.
있다면 기존 블록은 그대로 두고, 그 안에 "mysql" 블록만 추가합니다.
블록 사이에 쉼표가 있고 마지막 블록 뒤에는 쉼표가 없는지 확인한 뒤 저장합니다.

3. 연결 확인하기

→ 실습용 DB를 만들고, 앱을 재시작해 연결 성공을 화면에서 확인합니다.

3.1 실습용 DB 먼저 만들기

설정 파일의 MYSQL_DB에 적은 inventory가 실제로 있어야 연결 확인이 깔끔합니다. 데이터는 3강에서 채우므로, 지금은 빈 DB만 만들어 둡니다.

이때 CREATE DATABASE는 터미널에 그냥 입력하는 리눅스 명령이 아니라 MySQL 안에서 실행하는 SQL입니다. 먼저 터미널에서 MySQL에 접속합니다.

sudo mysql -u root -p

비밀번호를 입력하면 프롬프트가 mysql>로 바뀝니다. 여기서부터가 SQL을 입력하는 자리입니다. 아래 명령으로 DB를 만들고, 목록에서 확인한 뒤 빠져나옵니다.

CREATE DATABASE inventory DEFAULT CHARACTER SET utf8mb4;
SHOW DATABASES;
exit

각 SQL 끝에는 세미콜론(;)을 붙입니다. SHOW DATABASES; 결과 목록에 inventory가 보이면 정상입니다. MySQL Workbench 같은 GUI 도구를 쓴다면 쿼리 창에 같은 SQL을 붙여넣어 실행해도 됩니다.

▶ 지금 해보세요

터미널에서 sudo mysql -u root -p로 MySQL에 접속합니다.
mysql> 프롬프트에서 CREATE DATABASE inventory DEFAULT CHARACTER SET utf8mb4;를 실행합니다.
SHOW DATABASES;로 inventory가 보이는지 확인한 뒤 exit로 나옵니다.

💡 팁: 우분투 기본 설치에서는 sudo mysql(소켓 인증)로는 접속돼도 비밀번호를 쓰는 mysql -u root -p 접속은 막혀 있는 경우가 있습니다. Access denied가 나오면 root 비밀번호 설정 또는 실습 전용 계정 생성이 필요하며, 이는 4강의 계정·권한 설정에서 다룹니다.

3.2 앱 완전 재시작하고 확인하기

Claude Desktop 설정 파일은 앱이 켜질 때만 읽히므로, 저장 후에는 완전 종료 후 재시작해야 반영됩니다.

창을 닫는 것만으로는 부족합니다. 프로세스를 종료시키세요.

pkill -f claude-desktop

재시작하면 입력창 근처의 도구 아이콘 목록에 mysql이 나타납니다. 이어서 대화로도 확인합니다.

3.3 명령하기

지금 연결된 MySQL의 데이터베이스 목록을 보여줘

응답에 inventory가 포함된 목록이 표로 나오면 연결에 성공한 것입니다.

▶ 지금 해보세요

MySQL에서 CREATE DATABASE inventory DEFAULT CHARACTER SET utf8mb4;를 실행합니다.
Claude Desktop을 완전히 종료했다가 다시 실행합니다.
도구 아이콘에 mysql이 보이면, 채팅에 "DB 목록 보여줘"를 입력해 inventory가 나오는지 확인합니다.

💡 팁: 우분투에서 창을 닫아도 앱이 백그라운드에 남아 설정이 다시 로드되지 않을 수 있습니다. 확실히 하려면 터미널에서 pkill -f claude-desktop으로 종료한 뒤 다시 실행하세요. Windows는 트레이 아이콘에서 우클릭 → 종료, macOS는 Cmd+Q로 완전 종료합니다.

✔ 확인 기준: 도구 아이콘에 mysql이 보이고, "DB 목록 보여줘" 응답에 inventory가 나오면 연결 완료입니다. 이 화면을 캡처해 두면 중간 체크포인트 제출 자료가 됩니다.

4. 연결 실패 시 진단하기

→ 증상별 원인과 해결을 바깥에서 안쪽 순서로 확인합니다.

연결이 안 될 때는 JSON 문법 → Node.js → MySQL 접속 정보 순으로, 바깥에서 안쪽으로 좁혀 갑니다. 아래 표에서 내 증상을 찾아 해당 조치를 먼저 시도하세요.

증상	원인과 조치
도구 아이콘에 mysql이 아예 없음	JSON 문법 오류. 쉼표·중괄호를 확인하고 jsonlint.com에서 검사
목록엔 있는데 빨간 표시·오류	Node.js 문제 또는 첫 다운로드 지연. `npx -v` 확인 후 1~2분 기다렸다가 재시작
Access denied	계정·비밀번호 불일치. `mysql -u root -p`로 같은 정보가 되는지 검증
Unknown database	DB 미생성. `CREATE DATABASE inventory;` 실행
ECONNREFUSED	MySQL 서비스 꺼짐. `sudo systemctl start mysql`로 시작

💡 팁: 가장 흔한 실패는 JSON trailing comma(마지막 항목 뒤 쉼표)입니다. 오류의 90%가 여기서 납니다.

첫 실행은 npx가 서버 패키지를 처음 내려받느라 수십 초~수 분 걸립니다. 이를 고장으로 오해하지 마세요. 수업 전 터미널에서 npx -y @benborla29/mcp-server-mysql를 한 번 실행해 캐시를 만들어 두면(실행 후 Ctrl+C 종료) 대기 시간이 줄어듭니다.

→ 다음 강의 (3강): 이번에 연결한 inventory DB에 실습용 테이블과 데이터를 채우고, 자연어로 조회하면서 Claude가 만든 SQL을 검증하는 습관을 익힙니다.

2. Claude MCP & MySQL 환경설정

0. 학습 목표

0.1 이번 글에서 다룰 내용

1. Claude가 MySQL을 다루는 원리

1.1 MCP — AI와 도구를 잇는 표준 규격

1.2 Host · Client · Server 구조

1.3 자연어가 SQL로 실행되는 흐름

1.4 설정 파일이 하는 일

2. 설정 파일 작성하기

2.1 Node.js 설치하기

2.2 Claude MCP 설정 파일 위치 찾기

2.2 MySQL MCP 서버 등록하기

2.3 파일에 이미 다른 내용이 있을 때

3. 연결 확인하기

3.1 실습용 DB 먼저 만들기

3.2 앱 완전 재시작하고 확인하기

3.3 명령하기

4. 연결 실패 시 진단하기

댓글

이 글 공유하기

티스토리툴바

0. 학습 목표

0.1 이번 글에서 다룰 내용

1. Claude가 MySQL을 다루는 원리

1.1 MCP — AI와 도구를 잇는 표준 규격

1.2 Host · Client · Server 구조

1.3 자연어가 SQL로 실행되는 흐름

1.4 설정 파일이 하는 일

2. 설정 파일 작성하기

2.1 Node.js 설치하기

2.2 Claude MCP 설정 파일 위치 찾기

2.2 MySQL MCP 서버 등록하기

2.3 파일에 이미 다른 내용이 있을 때

3. 연결 확인하기

3.1 실습용 DB 먼저 만들기

3.2 앱 완전 재시작하고 확인하기

3.3 명령하기

4. 연결 실패 시 진단하기

댓글

이 글 공유하기

다른 글

1. Claude Desktop 설치

티스토리툴바