Atlan

공식

Atlan의 공식 MCP 서버로, 메타데이터의 힘을 AI 도구에 활용할 수 있게 해줍니다.

GitHub

Atlan MCP(으)로 무엇을 할 수 있나요?

자산 검색 — search_assets를 사용하여 조건에 따라 데이터 자산을 찾습니다.
DSL을 통한 자산 검색 — get_assets_by_dsl을 사용하여 도메인 특화 언어 쿼리로 자산을 가져옵니다.
데이터 계보 탐색 — traverse_lineage를 사용하여 자산의 상위 및 하위 관계를 추적합니다.
자산 메타데이터 업데이트 — update_assets를 통해 자산의 사용자 설명과 인증서 상태를 수정합니다.
비즈니스 용어집 관리 — create_glossaries, create_glossary_categories, create_glossary_terms를 사용하여 용어집, 카테고리, 용어를 생성합니다.
데이터 품질 규칙 관리 — create_dq_rules, update_dq_rules, schedule_dq_rules, delete_dq_rules로 데이터 품질 규칙을 생성, 업데이트, 예약, 삭제합니다.

문서

Atlan MCP 서버

[!WARNING] 이 로컬 MCP 서버는 더 이상 사용되지 않습니다. 대신 호스팅된 Atlan MCP를 mcp.atlan.com/mcp 에서 사용하세요.

로컬 설치 경로(Docker, uv 또는 pip install atlan-mcp-server)는 유지보수 전용 모드로, 새로운 기능이 제공되지 않으며 지원이 보장되지 않습니다. 호스팅 엔드포인트는 Atlan을 Claude Desktop, Cursor, Codex, Databricks UC 및 기타 MCP 클라이언트와 통합하는 데 권장되는 방법입니다. 설정 방법은 Atlan MCP 개요를 참조하세요.

Atlan 모델 컨텍스트 프로토콜 서버를 사용하면 AI 에이전트가 Atlan 서비스와 상호 작용할 수 있습니다.

빠른 시작

문서를 따라 Atlan API 키를 생성합니다.
선호도에 따라 다음 방법 중 하나를 선택합니다:
- Docker를 통한 설치 - Docker 컨테이너 사용 (권장)
- uv를 통한 설치 - UV 패키지 관리자 사용

[!NOTE] 구성 파일에서 <YOUR_API_KEY>, <YOUR_INSTANCE>, <YOUR_AGENT_ID>을 각각 실제 Atlan API 키, 인스턴스 URL, 에이전트 ID(선택 사항)로 교체해야 합니다.

Docker를 통한 설치

사전 요구 사항:

운영 체제에 맞는 공식 Docker 설치 가이드를 따릅니다.
Docker가 실행 중인지 확인합니다:
```
docker --version
```

Claude Desktop에 추가

Claude > Settings > Developer > Edit Config > claude_desktop_config.json로 이동하여 다음을 추가합니다:

{
  "mcpServers": {
    "atlan": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "ATLAN_API_KEY=<YOUR_API_KEY>",
        "-e",
        "ATLAN_BASE_URL=https://<YOUR_INSTANCE>.atlan.com",
        "-e",
        "ATLAN_AGENT_ID=<YOUR_AGENT_ID>",
        "ghcr.io/atlanhq/atlan-mcp-server:latest"
      ]
    }
  }
}

Cursor에 추가

Cursor > Settings > Tools & Integrations > New MCP Server을 열어 다음을 포함시킵니다:

{
  "mcpServers": {
    "atlan": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "ATLAN_API_KEY=<YOUR_API_KEY>",
        "-e",
        "ATLAN_BASE_URL=https://<YOUR_INSTANCE>.atlan.com",
        "-e",
        "ATLAN_AGENT_ID=<YOUR_AGENT_ID>",
        "ghcr.io/atlanhq/atlan-mcp-server:latest"
      ]
    }
  }
}

uv를 통한 설치

사전 요구 사항:

uv 설치:

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Alternative: if you already have Python/pip
pip install uv

설치 확인:
```
uv --version
```

[!NOTE] uv를 사용하면 uvx이 실행될 때마다 자동으로 최신 버전을 가져옵니다. 더 예측 가능한 동작을 원한다면 Docker 옵션을 고려하세요.

Claude Desktop에 추가

Claude > Settings > Developer > Edit Config > claude_desktop_config.json로 이동하여 다음을 포함시킵니다:

{
  "mcpServers": {
    "atlan": {
      "command": "uvx",
      "args": ["atlan-mcp-server"],
      "env": {
        "ATLAN_API_KEY": "<YOUR_API_KEY>",
        "ATLAN_BASE_URL": "https://<YOUR_INSTANCE>.atlan.com",
        "ATLAN_AGENT_ID": "<YOUR_AGENT_ID>"
      }
    }
  }
}

Cursor에 추가

Cursor > Settings > Tools & Integrations > New MCP Server을 열어 다음을 포함시킵니다:

{
  "mcpServers": {
    "atlan": {
      "command": "uvx",
      "args": ["atlan-mcp-server"],
      "env": {
        "ATLAN_API_KEY": "<YOUR_API_KEY>",
        "ATLAN_BASE_URL": "https://<YOUR_INSTANCE>.atlan.com",
        "ATLAN_AGENT_ID": "<YOUR_AGENT_ID>"
      }
    }
  }
}

사용 가능한 도구

도구	설명
`search_assets`	조건에 따라 자산 검색
`get_assets_by_dsl`	DSL 쿼리를 사용하여 자산 검색
`traverse_lineage`	자산의 계보 검색
`update_assets`	자산 속성 업데이트 (사용자 설명 및 인증서 상태)
`create_glossaries`	용어집 생성
`create_glossary_categories`	용어집 카테고리 생성
`create_glossary_terms`	용어집 용어 생성
`create_dq_rules`	테이블, 뷰, 구체화된 뷰 또는 SnowflakeDynamicTable 자산에 대한 데이터 품질 규칙 생성 (열 수준, 테이블 수준, 사용자 지정 SQL)
`update_dq_rules`	기존 데이터 품질 규칙 업데이트 (임계값, 우선순위, 조건 등)
`schedule_dq_rules`	cron 표현식을 사용하여 자산에 대한 데이터 품질 규칙 실행 예약
`delete_dq_rules`	GUID로 하나 이상의 데이터 품질 규칙 삭제
`query_asset`	테이블/뷰 자산에 대해 SQL 쿼리 실행

도구 접근 제어

Atlan MCP 서버에는 사용자가 사용할 수 있는 도구를 제어할 수 있는 구성 가능한 도구 제한 미들웨어가 포함되어 있습니다. 이는 역할 기반 접근 제어를 구현하거나 특정 환경에서 특정 작업을 제한하는 데 유용합니다.

도구 제한

RESTRICTED_TOOLS 환경 변수를 사용하여 특정 도구에 대한 접근을 제한할 수 있습니다. 차단할 도구 이름을 쉼표로 구분하여 제공합니다:

Docker 구성

{
  "mcpServers": {
    "atlan": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "ATLAN_API_KEY=<YOUR_API_KEY>",
        "-e",
        "ATLAN_BASE_URL=https://<YOUR_INSTANCE>.atlan.com",
        "-e",
        "ATLAN_AGENT_ID=<YOUR_AGENT_ID>",
        "-e",
        "RESTRICTED_TOOLS=get_assets_by_dsl_tool,update_assets_tool",
        "ghcr.io/atlanhq/atlan-mcp-server:latest"
      ]
    }
  }
}

uv 구성

{
  "mcpServers": {
    "atlan": {
      "command": "uvx",
      "args": ["atlan-mcp-server"],
      "env": {
        "ATLAN_API_KEY": "<YOUR_API_KEY>",
        "ATLAN_BASE_URL": "https://<YOUR_INSTANCE>.atlan.com",
        "ATLAN_AGENT_ID": "<YOUR_AGENT_ID>",
        "RESTRICTED_TOOLS": "get_assets_by_dsl_tool,update_assets_tool"
      }
    }
  }
}

제한 가능한 도구 이름

다음 도구 중 하나를 제한할 수 있습니다:

search_assets_tool - 자산 검색 기능
get_assets_by_dsl_tool - DSL 쿼리 실행
traverse_lineage_tool - 계보 탐색
update_assets_tool - 자산 업데이트 (설명, 인증서)
create_glossaries - 용어집 생성
create_glossary_categories - 카테고리 생성
create_glossary_terms - 용어 생성
create_dq_rules_tool - 데이터 품질 규칙 생성
update_dq_rules_tool - 데이터 품질 규칙 업데이트
schedule_dq_rules_tool - 데이터 품질 규칙 예약
delete_dq_rules_tool - 데이터 품질 규칙 삭제

일반적인 사용 사례

읽기 전용 접근

모든 쓰기 작업 제한:

RESTRICTED_TOOLS=update_assets_tool,create_glossaries,create_glossary_categories,create_glossary_terms,create_dq_rules_tool,update_dq_rules_tool,schedule_dq_rules_tool,delete_dq_rules_tool

DSL 쿼리 비활성화

보안 또는 성능상의 이유로:

RESTRICTED_TOOLS=get_assets_by_dsl_tool

최소 접근

기본 검색만 허용:

RESTRICTED_TOOLS=get_assets_by_dsl_tool,update_assets_tool,traverse_lineage_tool,create_glossaries,create_glossary_categories,create_glossary_terms,create_dq_rules_tool,update_dq_rules_tool,schedule_dq_rules_tool,delete_dq_rules_tool

작동 방식

도구가 제한된 경우:

목록에서 숨김: 클라이언트가 사용 가능한 도구를 요청할 때 제한된 도구가 나타나지 않습니다.
실행 차단: 누군가 제한된 도구를 실행하려고 하면 명확한 오류 메시지가 표시됩니다.
로깅: 모든 접근 결정은 모니터링 및 디버깅을 위해 기록됩니다.

제한 없음 (기본값)

RESTRICTED_TOOLS 환경 변수를 설정하지 않으면 기본적으로 모든 도구를 사용할 수 있습니다.

전송 모드

Atlan MCP 서버는 세 가지 전송 모드를 지원하며, 각각 다른 배포 시나리오에 최적화되어 있습니다. MCP 전송 모드에 대한 자세한 내용은 공식 MCP 문서를 참조하세요.

전송 모드	사용 사례	이점	사용 시기
stdio (기본값)	로컬 개발, IDE 통합	간단하고 직접적인 통신	Claude Desktop, Cursor IDE
SSE (서버 전송 이벤트)	원격 배포, 웹 브라우저	실시간 스트리밍, 웹 호환	클라우드 배포, 웹 클라이언트
streamable-http	HTTP 기반 원격 연결	표준 HTTP, 로드 밸런서 친화적	Kubernetes, 컨테이너화된 배포

포괄적인 배포 지침, 구성 예제 및 프로덕션 모범 사례는 배포 가이드를 참조하세요.

프로덕션 배포

Atlan MCP 컨테이너 이미지를 선택한 클라우드/플랫폼에 호스팅합니다.
필요한 모든 환경 변수를 추가했는지 확인합니다.
배포 시나리오에 적합한 전송 모드를 선택합니다. 프로덕션에는 SSE 전송이 권장됩니다 (-e MCP_TRANSPORT=sse).
자세한 배포 시나리오 및 구성은 배포 가이드를 참조하세요.

원격 MCP 구성

현재 일반적으로 사용 가능한 Atlan용 원격 MCP 서버는 없습니다.

mcp-remote 로컬 프록시 도구를 사용하여 원격 MCP 서버에 연결할 수 있습니다.

이를 통해 실제 MCP 클라이언트와의 원격 MCP 서버 상호 작용이 어떤지 테스트할 수 있습니다.

{
  "mcpServers": {
    "math": {
      "command": "npx",
      "args": ["mcp-remote", "https://hosted-domain"]
    }
  }
}

로컬에서 개발하기

로컬에서 개발하고 싶으신가요? 단계별 안내를 보려면 로컬 빌드 가이드를 확인하세요!

도움이 필요하신가요?

질문이나 피드백이 있으면 support@atlan.com으로 문의하세요.
GitHub 이슈를 직접 생성하시면 답변해 드리겠습니다.

자주 묻는 질문

Python이 설치되어 있어야 하나요?

간단한 답변: 설치 방법에 따라 다릅니다.

Docker (권장): 호스트 머신에 Python 설치가 필요하지 않습니다. 컨테이너에 필요한 모든 것이 포함되어 있습니다.
uv: Python 런타임이 필요하지만, uv가 아직 사용할 수 없는 경우 Python 3.11+를 자동으로 다운로드하여 관리합니다.

기술 세부 사항: Atlan MCP 서버는 Python 애플리케이션으로 구현됩니다. 모델 컨텍스트 프로토콜 자체는 언어에 구애받지 않지만, 현재 구현에는 Python 3.11+가 필요합니다.

문제 해결

Claude Desktop에 spawn uv ENOENT {"context":"connection","stack":"Error: spawn uv ENOENT\n at ChildProcess._handle.onexit와 유사한 오류가 표시되면, Claude가 uv를 찾을 수 없는 이 문제일 가능성이 높습니다. 해결 방법:
- uv가 설치되어 있고 PATH에서 사용 가능한지 확인합니다.
- which uv을 실행하여 설치 경로를 확인합니다.
- whereis uv를 실행하여 정확한 uv 경로를 가리키도록 Claude의 구성을 업데이트하고 해당 경로를 사용합니다.