@thinkdata/mcp-server

ThinkERD MCP Server — AI agents can query your database schema

📦 이 패키지는 @thinkdata/cli 로 통합되었습니다

구현이 @thinkdata/cli 의 mcp 모드로 옮겨갔고, 이 패키지는 이미 설정한 분들을 위한 별칭으로 남습니다. 종전 사용법(--api-url·--token·--dev)은 그대로 동작합니다.

새로 설정한다면 CLI 쪽을 쓰십시오:

{ "mcpServers": { "thinkerd": {
    "command": "npx", "args": ["-y", "@thinkdata/cli", "mcp"]
}}}

같은 패키지로 DB 스키마를 ERD에 반영(thinkdata extract)까지 되므로 설치가 한 번이면 끝납니다. 종전에는 조회는 이 패키지로, 반영은 CLI로 갈려 있어 둘을 각각 설치·설정해야 했습니다.

외부 AI 에이전트(Cursor, Windsurf, Claude Code, Claude Desktop 등)가 ThinkERD의 ERD 스키마를 실시간으로 조회하고, 스키마 변경을 제안할 수 있는 Model Context Protocol (MCP) 서버입니다.

주요 기능

• Schema Read — 다이어그램의 엔터티, 컬럼, 관계를 AI 에이전트의 컨텍스트로 제공
• DDL 생성 — PostgreSQL, MySQL, Oracle, MSSQL, SQLite DDL 자동 생성
• 스키마 검증 — PK 누락, 고립 엔터티, 빈 테이블 등 자동 점검
• 스키마 변경 제안 — AI가 코드를 작성하다 필요한 스키마 변경을 ThinkERD에 Draft로 전송

빠른 시작

1. 토큰 발급

ThinkERD 캔버스 설정(My Settings) → Developer & API 탭 → 새 토큰 생성

토큰 발급은 Pro 이상 플랜에서 가능합니다.

스코프는 필요한 만큼만 주십시오. read만 있는 토큰으로는 쓰기 도구 (propose_schema_change)를 호출할 수 없습니다. 워크스페이스를 지정해 발급하면 그 워크스페이스 밖의 리소스는 조회되지 않습니다.

2. IDE 설정

Cursor (~/.cursor/mcp.json)

{
  "mcpServers": {
    "thinkerd": {
      "command": "npx",
      "args": ["-y", "@thinkdata/mcp-server", "--api-url", "https://api.thinkerd.io", "--token", "<YOUR_TOKEN>"]
    }
  }
}

Windsurf (~/.codeium/windsurf/mcp_config.json)

{
  "mcpServers": {
    "thinkerd": {
      "command": "npx",
      "args": ["-y", "@thinkdata/mcp-server", "--api-url", "https://api.thinkerd.io", "--token", "<YOUR_TOKEN>"]
    }
  }
}

Claude Code (레포 루트 .mcp.json)

CLI로 붙이는 것이 가장 간단합니다:

claude mcp add --scope user thinkerd -- npx -y @thinkdata/mcp-server \
  --api-url https://api.thinkerd.io --token <YOUR_TOKEN>

스코프는 셋입니다 — local(기본, 나만·이 프로젝트만) · project(레포 루트 .mcp.json, 팀 공유) · user(내 모든 프로젝트). 팀과 공유하려면 레포 루트 .mcp.json에 직접 적습니다:

{
  "mcpServers": {
    "thinkerd": {
      "command": "npx",
      "args": ["-y", "@thinkdata/mcp-server", "--api-url", "https://api.thinkerd.io"]
    }
  }
}

⚠️ Claude Code는 Claude Desktop의 claude_desktop_config.json을 읽지 않습니다. 이름이 비슷해 그쪽 경로를 따라가는 경우가 있는데, JSON 형식은 같아도 파일이 다릅니다.

그리고 .mcp.json은 보통 버전 관리에 올라갑니다. 위 예시가 --token을 빼고 있는 이유입니다 — 토큰은 THINKERD_TOKEN 환경변수로 넘기십시오(환경변수). 설정 파일에 평문으로 적으면 그대로 커밋됩니다.

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json)

{
  "mcpServers": {
    "thinkerd": {
      "command": "npx",
      "args": ["-y", "@thinkdata/mcp-server", "--api-url", "https://api.thinkerd.io", "--token", "<YOUR_TOKEN>"]
    }
  }
}

3. 사용 예시

AI 채팅에서 다음과 같이 요청하세요:

• "ThinkERD에서 결제 관련 테이블 스키마를 가져와서 TypeORM 엔티티 코드를 만들어줘"
• "ThinkERD 다이어그램의 DDL을 PostgreSQL로 생성해줘"
• "ThinkERD 스키마를 검증해서 문제가 있는지 확인해줘"

원격 연결

현재는 stdio 트랜스포트만 지원합니다(Cursor·Windsurf·Claude Code·Claude Desktop 등 로컬 호스트).

--sse 모드는 0.2.0에서 제거했습니다. 구현이 모듈 스코프에 트랜스포트 하나만 두고 있어 두 번째 클라이언트가 첫 번째의 연결을 끊었고, MCP 스펙에서도 SSE는 Streamable HTTP로 대체되는 폐기 경로입니다. 원격 연결은 호스티드 방식으로 별도 제공할 예정입니다.

Resources (읽기 전용)

| Resource URI | 설명 | |---|---| | thinkerd://diagrams | 모든 다이어그램 목록 | | thinkerd://diagrams/{id}/schema | 다이어그램 전체 스키마 (JSON) | | thinkerd://diagrams/{id}/entities/{id} | 단일 엔터티 상세 | | thinkerd://diagrams/{id}/ddl | DDL 생성 | | thinkerd://projects/{id}/dictionary | 표준 사전 |

Tools (액션 실행)

정본은 src/toolManifest.ts이며 toolContract.test.ts가 등록 목록과 대조합니다. 도구를 추가·삭제하면 매니페스트와 이 표를 함께 고쳐야 합니다.

스키마 조회

| Tool | 설명 | |---|---| | get_entity | 엔터티의 컬럼·타입·PK/FK 상세 조회 | | search_entities | 이름(논리명·물리명)으로 엔터티 검색 | | generate_ddl | DDL 생성 (PostgreSQL·MySQL·Oracle·MSSQL·SQLite) | | validate_schema | PK 누락·미연결 FK·비표준 네이밍 점검 | | harvest_schema_semantics | 물리 테이블에서 논리명·설명·관계를 역공학 추론 | | propose_schema_change | 스키마 변경 제안 (사용자 승인이 필요한 Draft로 전송) | | get_business_dictionary | 표준 단어·용어 사전 검색 → 논리명-물리명 매핑 가이드 | | analyze_legacy_sql | 레거시 SQL을 분석해 등장 테이블의 업무 의미·연관 관계 반환 |

의미 계층 · 온톨로지

| Tool | 설명 | |---|---| | get_project_context | 업무 용어가 섞인 질문에는 이것을 먼저. 자연어 질문으로 프로젝트 전체에서 관련 엔터티를 찾는다 | | semantic_search | 업무 용어로 엔터티·컬럼 검색 (동의어·설명·논리명 매칭, 매칭 유형 반환) | | get_business_context | 한 엔터티의 업무 의미·동의어·코드값·관계 전체 | | generate_sql | 한 다이어그램의 물리 스키마만 보고 SQL 작성용 컨텍스트 반환 | | find_join_path | 두 엔터티 간 최적 JOIN 경로 (BFS 최단 경로 + 중간 테이블·관계명) | | get_project_summary | 엔터티·관계 수, 주제영역 구성, RDF 트리플 수 등 전체 요약 | | query_ontology | 온톨로지 그래프에 SPARQL 직접 실행 (고급) | | check_metadata_quality | 메타데이터 풍부도 분석 + 개선 필요 엔터티 제안 |

환경변수

| 변수 | 설명 | 기본값 | |---|---|---| | THINKERD_API_URL | ThinkERD API URL | https://api.thinkerd.io | | THINKERD_TOKEN | Personal Access Token | — |

보안

• 토큰은 SHA-256 해시로만 서버에 저장됩니다
• 기본 발급 시 read 스코프만 부여됩니다
• 워크스페이스/프로젝트 단위로 접근 범위를 제한할 수 있습니다
• 토큰 만료일을 설정할 수 있습니다 (기본 90일)

라이선스

MIT