# AI 연동(MCP)

> Claude 같은 AI 에이전트가 sqemo-mcp로 ERD를 읽고, 린트하고, 편집하게 합니다 — npx로 실행되는 로컬 MCP 서버.

[sqemo-mcp](https://www.npmjs.com/package/sqemo-mcp)는 AI 에이전트가 ERD를 다루게
하는 로컬 MCP(Model Context Protocol) 서버입니다: 엔터티·속성·관계 읽기와 편집,
SQL·DBML 가져오기·내보내기, 팀 표준에 따른 물리명 생성·검사, 린트·자동 배치·diff,
그리고 Pro에서는 실제 데이터베이스를 읽어 가져오거나 드리프트를 검사합니다. `npx`로
실행됩니다 — 별도 설치가 없습니다.

## 요구 사항

Node.js 22 이상.

## 클라이언트 설정

**Claude Code** — 프로젝트 루트의 `.mcp.json`에 추가:

```json
{
  "mcpServers": {
    "sqemo": { "command": "npx", "args": ["-y", "sqemo-mcp"] }
  }
}
```

**Claude Desktop** — 설정 파일에 같은 `mcpServers` 항목을 추가:

- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`

**Codex CLI** — 명령 하나로 등록:

```bash
codex mcp add sqemo -- npx -y sqemo-mcp
```

또는 `~/.codex/config.toml`에 같은 내용의 TOML을 추가:

```toml
[mcp_servers.sqemo]
command = "npx"
args = ["-y", "sqemo-mcp"]
```

다른 대부분의 MCP 클라이언트(Cursor 등)도 같은 `mcpServers` JSON을 씁니다.

> 이미 AI 에이전트를 쓰고 있다면, 이 페이지 URL을 Claude Code·Codex·Cursor에 붙여
> 넣고 sqemo MCP 서버를 연결해 달라고 하세요 — 위 단계가 필요한 전부입니다.

## 서버 ERD를 쓰려면 로그인

로컬 `.erd.json` 파일에는 로그인이 필요 없습니다 — 파일 도구는 전부 오프라인으로
동작합니다. Sqemo 서버에 저장된 ERD를 읽거나 편집하려면 터미널에서 한 번 로그인합니다:

```bash
npx sqemo-mcp login    # Google, GitHub, 또는 이메일 + 비밀번호 선택
npx sqemo-mcp logout   # 저장된 자격 증명 삭제
```

`login`은 로그인 방식을 묻습니다. Google과 GitHub은 브라우저 탭을 열고 결과를
터미널로 돌려주며, 세 번째 옵션은 터미널을 떠나지 않고 이메일과 비밀번호를 받습니다.
어느 쪽이든 저장되는 것은 리프레시 토큰뿐이며(`~/.erdmaker/credentials.json`) —
비밀번호는 절대 저장되지 않습니다.

그 기기에 브라우저가 없다면 `npx sqemo-mcp login --password`를 쓰거나, 무인 실행에는
`SQEMO_EMAIL` / `SQEMO_PASSWORD`를 설정하세요.

## 에이전트 없이 CI에서

이 패키지는 파이프라인용 오프라인 CLI로도 동작합니다:

```bash
# 명명 표준 위반이 있으면 빌드 실패(종료 코드 1)
npx sqemo-mcp lint schema.erd.json

# SQL 또는 DBML을 stdout으로 내보내기
npx sqemo-mcp export schema.erd.json --format sql --dialect postgres > schema.sql
```

GitHub Actions:

```yaml
- run: npx sqemo-mcp lint schema.erd.json
```

## CI 드리프트 검사(Pro)

Pro에서는 `lint`가 ERD를 실제 데이터베이스와 비교해 서로 어긋났으면 CI를 실패시킬 수
있습니다. Google/GitHub으로 가입했을 때 비밀번호를 설정하는 법, 데이터베이스가 없을 때
Docker로 시험하는 법까지 단계별 안내는
[실제 데이터베이스 연결](/ko/docs/live-database/)을 보세요.

```yaml
# .github/workflows/schema-drift.yml
- run: npx sqemo-mcp lint erd/app.erd.json --db "$DATABASE_URL" --ignore "flyway_*"
  env:
    DATABASE_URL: ${{ secrets.DATABASE_URL }}   # 읽기 전용 계정 권장
    SQEMO_EMAIL: ${{ secrets.SQEMO_EMAIL }}     # Sqemo Pro 계정 (비밀번호 로그인;
    SQEMO_PASSWORD: ${{ secrets.SQEMO_PASSWORD }} # OAuth 전용 계정은 먼저 비밀번호 설정)
```

`SQEMO_EMAIL`/`SQEMO_PASSWORD`는 CI 작업이 도는 동안만 로그인합니다 — `login` 단계나
저장된 토큰이 필요 없습니다. 대화형 로그인은 브라우저를 쓸 수 있지만 CI 작업에는
브라우저가 없으므로 비밀번호가 필요합니다. Google/GitHub OAuth로 만든 Sqemo 계정에는
아직 비밀번호가 없습니다 —
[한 번 설정한 뒤](/ko/docs/live-database/#googlegithub으로-가입했다면-ci용-비밀번호를-한-번-설정)
여기 쓰세요. 인트로스펙션 자체는 CI 작업 안에서 실행되며 `information_schema`만
조회합니다 — 데이터베이스 접속 정보는 Sqemo로 전송되지 않습니다.

CI에 데이터베이스 자격 증명을 아예 두고 싶지 않다면 스키마 덤프와 비교하세요. 이것도
로그인이 필요 없습니다:

```bash
npx sqemo-mcp lint erd/app.erd.json --schema schema.sql --dialect postgres
```

## 에이전트가 할 수 있는 것

도구는 총 39개입니다. 몇 가지만 들면: `get_erd_overview`, `upsert_entity`,
`upsert_attribute`, `upsert_relationship`, `upsert_attributes`,
`upsert_dictionary_words`와 `upsert_domains`(한 번의 저장으로 일괄 편집), `import_sql`,
`import_dbml`, `export_sql`, `export_dbml`, `generate_physical_name`, `check_naming`,
`lint_erd`, `auto_layout`, `diff_erds`, 팀 표준에 새 단어를 제안하는 제안 도구들(승인·
반려는 여전히 사람이 합니다 — 그쪽은 [2분 영상](https://youtu.be/wHsoFbak6GY)에
있습니다), 그리고 실제 데이터베이스를 상대하는 Pro 도구 둘: `introspect_db`(라이브
PostgreSQL/MySQL 스키마를 ERD로 가져오기, 읽기 전용)와 `check_db_drift`(라이브
데이터베이스나 스키마 덤프가 ERD에서 어긋났는지 검사).

---
Source: https://sqemo.com/ko/docs/mcp/ · Updated 2026-08-29