← 목록으로AI WORKFLOW

로컬 DB를 Claude에 직접 연결하기 — MCP SQLite 연동과 아카이브된 서버 살리기

seungjin11 min2026-09-07
로컬 DB를 Claude에 직접 연결하기 — MCP SQLite 연동과 아카이브된 서버 살리기

CSV를 붙여넣는 대신 질문하기

로컬에 SQLite 파일 하나가 있다고 해봅시다. 여태 하던 순서는 대개 이렇습니다. 쿼리를 직접 짜서 결과를 CSV로 뽑고, 그걸 채팅창에 붙여넣고, 요약해달라고 합니다.

MCP를 붙이면 이 순서가 뒤집힙니다. “지난달 주문 중에 금액이 튀는 건이 있어?“라고 물으면 모델이 알아서 스키마를 조회하고, 쿼리를 짜고, 실행하고, 결과를 읽습니다. SQL은 제 손을 거치지 않습니다.

Figma를 붙였던 MCP 1편이 남의 서비스를 가져다 쓰는 이야기였다면, 이번엔 제 파일입니다. SQLite는 서버를 띄울 필요가 없으니 붙이기로는 가장 쉬운 소재입니다.

다만 검색해서 나오는 방법을 그대로 따라 하면 지금은 실패합니다. 그 이야기부터 해야겠습니다.

대부분의 가이드가 알려주는 명령은 지금 안 됩니다

한국어 자료든 영어 자료든 대개 이 명령을 알려줍니다.

uvx mcp-server-sqlite --db-path /path/to/database.db

오늘 기준으로 이걸 실행하면 서버가 뜨다 말고 죽습니다. 제가 받은 오류는 이겁니다.

AttributeError: 'Server' object has no attribute 'list_resources'

설정 파일 문제도 아니고 경로 문제도 아닙니다. 서버 자체가 최신 SDK에서 안 돕니다.

원인은 아카이브 + 열린 의존성

세 가지가 겹쳤습니다.

공식 SQLite 서버는 아카이브됐습니다. 2025년 5월 29일부로 modelcontextprotocol/servers 저장소에서 빠져 servers-archived로 옮겨졌습니다. PyPI 페이지에도 “더 이상 업데이트되지 않는다”는 배너가 붙어 있고, 마지막 릴리스는 2025년 4월 25일의 2025.4.25입니다.

지금 본 저장소에 남아 있는 레퍼런스 서버는 일곱 개뿐입니다. Everything, Fetch, Filesystem, Git, Memory, Sequential Thinking, Time. SQLite는 없습니다.

의존성에 상한이 없습니다. 아카이브된 패키지가 선언한 요구사항은 mcp[cli]>=1.6.0 하나뿐입니다. 위쪽이 열려 있으니 설치할 때마다 최신 SDK를 끌어옵니다.

그 SDK가 2.0으로 올라가면서 API를 바꿨습니다. 오늘 설치되는 건 mcp 2.1.1이고, 여기서 Server.list_resources 같은 데코레이터가 사라졌습니다. 서버 코드는 2025년 4월에 멈춰 있는데 SDK만 앞으로 갔으니 첫 줄에서 터집니다.

정리하면 아무도 고칠 사람이 없는 상태로 방치된 조합입니다. 저장소가 읽기 전용이라 핀을 박아줄 사람도 없고요.

방법 1 — SDK를 1.x로 묶어서 그대로 쓰기

서버 코드 자체는 멀쩡합니다. SDK만 옛 버전으로 고정하면 됩니다.

uvx --with 'mcp[cli]<2' mcp-server-sqlite --db-path /Users/이름/data/demo.db

--with로 의존성을 하나 얹어서 실행하는 방식입니다. 저는 가상환경에 mcp[cli]<2를 설치해 확인했습니다. SDK가 1.29.1로 내려가자 서버가 제대로 떴고, 툴 여섯 개도 그대로 올라옵니다.

툴 하는 일
read_query SELECT 실행
write_query INSERT·UPDATE·DELETE 실행
create_table 테이블 생성
list_tables 테이블 목록
describe_table 스키마 조회
append_insight 발견한 내용을 메모 리소스에 추가

문서에 describe-table로 적힌 곳이 있는데, 실제 서버가 노출하는 이름은 밑줄을 쓴 describe_table입니다.

Claude Desktop 설정 파일은 여기 있습니다.

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "sqlite": {
      "command": "uvx",
      "args": [
        "--with", "mcp[cli]<2",
        "mcp-server-sqlite",
        "--db-path", "/Users/이름/data/demo.db"
      ]
    }
  }
}

경로는 반드시 절대경로로 씁니다. 상대경로를 쓰면 서버가 어느 디렉터리에서 뜨느냐에 따라 결과가 달라져서 조용히 실패합니다.

방법 2 — 관리되는 커뮤니티 서버 쓰기

핀을 박기 싫으면 유지보수되는 쪽으로 가면 됩니다. mcp-sqlite는 npm으로 바로 뜨고 별도 고정이 필요 없습니다.

npx -y mcp-sqlite /Users/이름/data/demo.db

이쪽은 붙여보니 툴이 여덟 개 올라옵니다. db_info, list_tables, get_table_schema, query, read_records, create_record, update_records, delete_records. 조회 계열이 더 잘게 나뉘어 있어 스키마 보기가 편한 대신, 레퍼런스 서버의 append_insight 같은 건 없습니다.

{
  "mcpServers": {
    "sqlite": {
      "command": "npx",
      "args": ["-y", "mcp-sqlite", "/Users/이름/data/demo.db"]
    }
  }
}

Claude Code에 붙일 때는 파일을 열 것도 없이 한 줄이면 끝납니다.

claude mcp add sqlite -- npx -y mcp-sqlite /Users/이름/data/demo.db

-- 뒤는 서버 실행 명령으로 그대로 넘어갑니다. 범위는 기본이 local이고, 팀과 공유하려면 -s project를 붙여 저장소의 .mcp.json에 남깁니다.

연결됐는지 확인하기

Claude Code에서는 /mcp를 치면 서버 목록과 상태, 툴 개수가 나옵니다. 터미널에서는 claude mcp list로도 같은 걸 봅니다. ✔ Connected가 아니면 아직 안 붙은 겁니다. 이 명령들을 포함한 전체 목록은 슬래시 명령어 정리에 있습니다.

Claude Desktop은 조용히 실패하는 편이라 로그를 봐야 합니다.

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

서버별 stderr는 mcp-server-이름.log에 따로 쌓입니다. 앞에서 본 AttributeError도 여기서 찾았습니다.

붙였으면 이렇게 시킵니다

한 번에 답을 요구하기보다 순서대로 좁혀 가는 쪽이 결과가 낫습니다.

  1. 스키마부터. “이 DB에 어떤 테이블이 있고 각각 무슨 컬럼이야?” 모델이 list_tables와 describe_table을 부릅니다.
  2. 집계. “월별 주문 건수와 매출 합계를 뽑아줘.” 여기서 read_query가 나갑니다.
  3. 이상치. “그중에 평균에서 크게 벗어난 건을 찾아줘.” 앞의 결과를 근거로 쿼리를 다시 짭니다.

모델이 스키마를 모르는 채로 집계부터 시키면 컬럼 이름을 지어냅니다. 1번은 건너뛰지 마세요.

위험한 건 write_query입니다

두 서버 모두 쓰기 툴을 품고 있습니다. 레퍼런스 서버에는 write_query와 create_table이, 커뮤니티 서버에는 update_records와 delete_records가 있습니다. 그리고 둘 다 읽기 전용 플래그가 없습니다.

“조심해서 쓰세요”로 넘길 문제가 아닙니다. Claude Code에서는 툴 단위로 실제로 막을 수 있습니다. .claude/settings.json에 이렇게 씁니다.

{
  "permissions": {
    "deny": [
      "mcp__sqlite__write_query",
      "mcp__sqlite__create_table"
    ]
  }
}

이건 “물어보고 실행”이 아닙니다. deny된 툴은 모델의 컨텍스트에서 아예 제거됩니다. 존재를 모르니 부를 수도 없습니다. 서버 전체를 막으려면 mcp__sqlite 한 줄이면 되고, mcp__sqlite__*도 같은 뜻입니다.

함정이 두 가지 있습니다. mcp__ 규칙에 괄호를 넣으면 설정 로딩 단계에서 그 줄이 통째로 무시됩니다. 인자 단위로 걸고 싶다면 --disallowedTools 플래그를 써야 합니다. 그리고 allow 규칙과 달리 deny는 폴더 신뢰 절차를 기다리지 않고 곧바로 적용됩니다.

더 확실한 건 파일을 하나 더 두는 겁니다. 운영 DB를 그대로 붙이지 말고 복사본을 만들어 그쪽 경로를 넘기세요. 툴 권한을 잘못 걸어도 원본은 안전합니다. 툴 정의가 모델에게 어떻게 보이는지는 Claude API 툴 스키마 쪽에 정리해 뒀습니다.

정리

  • 공식 SQLite 서버는 2025년 5월 29일 아카이브됐고, 지금 본 저장소의 레퍼런스 서버는 일곱 개뿐이다.
  • uvx mcp-server-sqlite를 그냥 실행하면 SDK 2.x와 충돌해 list_resources 오류로 죽는다.
  • 쓰려면 --with 'mcp[cli]<2'로 SDK를 묶고, 아니면 npx -y mcp-sqlite 쪽으로 간다.
  • 경로는 절대경로, 확인은 /mcp, 실패 원인은 ~/Library/Logs/Claude/mcp*.log.
  • 쓰기 툴은 permissions.deny로 컨텍스트에서 제거하고, 운영 DB 대신 복사본을 붙인다.

수치와 상태는 2026년 9월 7일 기준입니다. MCP 공식 문서와 아카이브된 SQLite 서버를 확인했고, 오류와 툴 목록은 직접 실행해 받은 것입니다. 아카이브된 패키지라 앞으로 더 깨질 수 있으니, 안 되면 SDK 버전부터 의심하세요.