AI 연동(MCP)

갱신 2026년 8월 29일

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

요구 사항

Node.js 22 이상.

클라이언트 설정

Claude Code — 프로젝트 루트의 .mcp.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 — 명령 하나로 등록:

codex mcp add sqemo -- npx -y sqemo-mcp

또는 ~/.codex/config.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를 읽거나 편집하려면 터미널에서 한 번 로그인합니다:

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로도 동작합니다:

# 명명 표준 위반이 있으면 빌드 실패(종료 코드 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:

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

CI 드리프트 검사(Pro)

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

# .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 계정에는 아직 비밀번호가 없습니다 — 한 번 설정한 뒤 여기 쓰세요. 인트로스펙션 자체는 CI 작업 안에서 실행되며 information_schema만 조회합니다 — 데이터베이스 접속 정보는 Sqemo로 전송되지 않습니다.

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

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분 영상에 있습니다), 그리고 실제 데이터베이스를 상대하는 Pro 도구 둘: introspect_db(라이브 PostgreSQL/MySQL 스키마를 ERD로 가져오기, 읽기 전용)와 check_db_drift(라이브 데이터베이스나 스키마 덤프가 ERD에서 어긋났는지 검사).