Claude Code

Claude Code(Anthropic의 terminal coding agent)를 MCP로 AI-ERD에 연결합니다.

AI-ERD MCP 서버 추가

claude mcp add 명령으로 AI-ERD를 user scope 에 등록합니다.

claude mcp add --scope user --transport http ai-erd https://ai-erd.com/mcp

--scope user 를 꼭 붙이세요. 빼면 claude mcp add 는 local scope 로 등록하는데, local 은 ai-erd init 이 쓰는 .mcp.json 보다 우선합니다 — 그러면 저장소의 역할이 영영 적용되지 않습니다. user scope 로 두면 ai-erd init 을 실행한 저장소에서는 그 저장소의 project 항목(역할이 붙은 ai-erd 서버)이 이기고, 나머지 폴더는 이 항목을 씁니다.

첫 tool call 시 Claude Code가 OAuth 요구사항을 감지하고 authorization 절차를 안내합니다.

브라우저 창이 AI-ERD authorization page로 열립니다.
로그인하거나 기존 세션을 사용합니다.
consent screen을 승인합니다.
Claude Code가 token을 받아 local session에 저장합니다.

연결 확인:

claude mcp list

이 user scope 연결에는 역할이 없습니다. 역할 없는 세션이면 서버가 Claude Code 에게, 이 저장소의 세션이 가질 역할을 사용자에게 묻고 그 답으로 ai-erd init 을 실행하라고 안내합니다. CLI → 저장소 설정 을 참고하세요.

npx -y ai-erd@latest init                     # 사람이 터미널에서: 역할과 프로젝트를 물어봄
npx -y ai-erd@latest init --role <역할>        # 에이전트가, 사용자가 고른 역할로

사용해 보기

Claude Code 세션에서:

List my AI-ERD ERD documents.

Claude Code가 mcp__ai-erd__list_documents를 type=erd로 호출하고 결과를 출력합니다.

Open ERD document <uuid> and show me the users table.

Claude Code는 mcp__ai-erd__erd_list_tables와 mcp__ai-erd__erd_get_table을 호출해 스키마를 보여줍니다.

설정 파일

파일을 손으로 고치기보다 위의 claude mcp add --scope user 명령을 쓰세요 — user scope 설정을 대신 써 줍니다(scope 별 저장 위치는 Claude Code MCP docs 참고).

저장소의 .mcp.json 은 ai-erd init 이 쓰며, 역할이 붙은 ai-erd 항목 하나가 들어갑니다.

{
  "mcpServers": {
    "ai-erd": {
      "command": "npx",
      "args": ["-y", "@ai-erd/mcp", "--role", "development"]
    }
  }
}

그런 저장소에 local scope 의 ai-erd 항목을 더하지 마세요. 이 항목을 가립니다.

Scope와 권한

AI-ERD가 발급한 token은 사용자 계정 범위로 동작합니다. Claude Code는 사용자가 볼 수 있거나 편집할 수 있는 document만 접근합니다.

OWNER / EDITOR — 읽기 + 쓰기 가능
VIEWER — 읽기 전용(write tool call은 permission error)

토큰은 AI-ERD 계정 설정 → Connected apps에서 언제든 revoke할 수 있습니다.

문제 해결

인증 중 브라우저가 열리지 않음
터미널에 표시된 authorization URL을 복사해 직접 여세요.

"plan does not include MCP"
MCP는 유료 요금제가 필요합니다. 계정 설정에서 업그레이드하거나 요금제를 참고하세요.

ai-erd init 뒤에도 역할이 적용되지 않음
역할은 새 세션부터 적용됩니다. 종료한 뒤 저장소에서 claude -c 로 이어 가고, .mcp.json 의 ai-erd 서버를 쓸지 물으면 승인하세요. 그래도 역할이 없으면 다른 ai-erd 항목이 가리고 있는 것입니다. claude mcp get ai-erd 로 확인해 local scope 라면 claude mcp remove ai-erd -s local 로 지우고 다시 시작하세요.

Tool call이 401을 반환함
토큰이 만료되었습니다. 아무 tool call이나 다시 실행하면 Claude Code가 refresh를 시도합니다. 필요하면 서버를 제거 후 다시 추가하세요.

AI-ERD MCP 서버 추가​

사용해 보기​

설정 파일​

Scope와 권한​

문제 해결​

AI-ERD MCP 서버 추가

사용해 보기

설정 파일

Scope와 권한

문제 해결