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

MCP로 Claude에 로컬 SQLite 연결하기. 아카이브된 레퍼런스 서버가 깨지는 원인과 설정 JSON.

- source: https://polroute.com/posts/mcp-sqlite-local-db/
- category: AI 워크플로우
- published: 2026-09-07

---

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

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

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

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

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

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

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

```bash
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만 옛 버전으로 고정하면 됩니다.

```bash
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`

```json
{
  "mcpServers": {
    "sqlite": {
      "command": "uvx",
      "args": [
        "--with", "mcp[cli]<2",
        "mcp-server-sqlite",
        "--db-path", "/Users/이름/data/demo.db"
      ]
    }
  }
}
```

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

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

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

```bash
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` 같은 건 없습니다.

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

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

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

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

## 연결됐는지 확인하기

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

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

```bash
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`에 이렇게 씁니다.

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

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

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

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

## 정리

- 공식 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 공식 문서](https://modelcontextprotocol.io/introduction)와 [아카이브된 SQLite 서버](https://github.com/modelcontextprotocol/servers-archived/tree/main/src/sqlite)를 확인했고, 오류와 툴 목록은 직접 실행해 받은 것입니다. 아카이브된 패키지라 앞으로 더 깨질 수 있으니, 안 되면 SDK 버전부터 의심하세요.