Keboola

Keboola MCP Server

AI 에이전트, MCP 클라이언트(Cursor, Claude, Windsurf, VS Code ...) 및 기타 AI 어시스턴트를 Keboola에 연결하세요. 글루 코드 없이 데이터, 변환, SQL 쿼리, 작업 트리거를 노출할 수 있습니다. 에이전트가 필요한 데이터에 필요한 시점과 위치에서 액세스할 수 있도록 제공하세요.

개요

Keboola MCP Server는 Keboola 프로젝트와 최신 AI 도구를 연결하는 오픈 소스 브리지입니다. 스토리지 액세스, SQL 변환, 작업 트리거와 같은 Keboola 기능을 Claude, Cursor, CrewAI, LangChain, Amazon Q 등에서 호출할 수 있는 도구로 바꿉니다.

• 빠른 시작
• 로컬 설정

기능

AI Agent와 MCP Server를 사용하면 다음을 수행할 수 있습니다.

• 스토리지: 테이블을 직접 쿼리하고 테이블 또는 버킷 설명을 관리합니다
• 컴포넌트: 추출기, 기록기, 데이터 앱, 변환 구성을 생성하고, 나열하고, 검사합니다
• SQL: 자연어로 SQL 변환을 생성합니다
• 작업: 컴포넌트와 변환을 실행하고 작업 실행 세부 정보를 가져옵니다
• 플로우: Conditional Flows와 Orchestrator Flows를 사용해 워크플로 파이프라인을 구축하고 관리합니다.
• 데이터 앱: 스토리지 데이터에 대한 쿼리를 표시하는 Keboola Data Apps를 생성, 배포, 관리합니다. Keboola 관리 리포지토리 또는 고객 GitHub 리포지토리(조직의 GitHub 연결을 통해 복제되며 저장된 자격 증명은 사용하지 않음)에 있는 python-js 앱과 Streamlit 앱을 지원합니다.
• 메타데이터: 자연어를 사용해 프로젝트 문서와 객체 메타데이터를 검색, 읽기, 업데이트합니다
• 개발 브랜치: 프로덕션 외부의 개발 브랜치에서 안전하게 작업하며, 모든 작업은 선택한 브랜치로 범위가 제한됩니다.

---

🚀 빠른 시작: 원격 MCP Server(가장 쉬운 방법)

Keboola MCP Server를 사용하는 가장 쉬운 방법은 원격 MCP Server를 이용하는 것입니다. 이 호스팅 솔루션을 사용하면 로컬 설정, 구성 또는 설치가 필요하지 않습니다.

원격 MCP Server란 무엇인가요?

원격 서버는 모든 멀티 테넌트 Keboola 스택에서 호스팅되며 OAuth 인증을 지원합니다. 원격 Streamable HTTP 연결과 OAuth 인증을 지원하는 모든 AI 어시스턴트에서 연결할 수 있습니다.

연결 방법

1. 원격 서버 URL 가져오기: Keboola 프로젝트 설정 → MCP Server 탭으로 이동합니다
2. 서버 URL 복사하기: URL은 다음과 같은 형식입니다: https://mcp.<YOUR_REGION>.keboola.com/mcp
3. AI 어시스턴트 구성하기: URL을 AI 어시스턴트의 MCP 설정에 붙여넣습니다
4. 인증하기: Keboola 계정으로 로그인하라는 메시지가 표시됩니다. 사용할 프로젝트는 이후 대화에서 선택합니다(예: "내 Keboola 프로젝트 나열해 줘" / "프로젝트 X 사용해 줘").

지원 클라이언트

• Cursor: 프로젝트의 MCP Server 설정에서 "Install In Cursor" 버튼을 사용하거나 다음 버튼을 클릭합니다
• Claude Desktop: 설정 → 통합에서 통합을 추가합니다
• Claude Code: claude mcp add --transport http keboola <URL>을 사용해 설치합니다(자세한 내용은 아래 참조).
• Windsurf: 원격 서버 URL로 구성합니다
• Make: 원격 서버 URL로 구성합니다
• 기타 MCP 클라이언트: 원격 서버 URL로 구성합니다

Claude Code 설정

Claude Code는 터미널에서 Claude와 상호작용할 수 있는 명령줄 인터페이스 도구입니다. 간단한 명령으로 Keboola MCP Server 통합을 설치할 수 있습니다.

설치:

터미널에서 다음 명령을 실행하고, <YOUR_REGION>을 Keboola 리전으로 바꿉니다.

claude mcp add --transport http keboola https://mcp.<YOUR_REGION>.keboola.com/mcp

리전별 명령:

리전	설치 명령
미국 버지니아 AWS	claude mcp add --transport http keboola https://mcp.keboola.com/mcp
미국 버지니아 GCP	claude mcp add --transport http keboola https://mcp.us-east4.gcp.keboola.com/mcp
EU 프랑크푸르트 AWS	claude mcp add --transport http keboola https://mcp.eu-central-1.keboola.com/mcp
EU 아일랜드 Azure	claude mcp add --transport http keboola https://mcp.north-europe.azure.keboola.com/mcp
EU 프랑크푸르트 GCP	claude mcp add --transport http keboola https://mcp.europe-west3.gcp.keboola.com/mcp

사용법:

설치가 완료되면 대화에서 /mcp을 입력하고 사용할 Keboola 도구를 선택해 Claude Code에서 Keboola MCP Server를 사용할 수 있습니다.

인증:

Claude Code에서 Keboola MCP Server를 처음 사용하면 브라우저 창이 열리고 다음을 요청합니다.

1. Keboola 계정으로 로그인
2. 연결 승인

인증이 완료되면 Claude Code에서 바로 Keboola 도구를 사용할 수 있습니다. 프로젝트는 이후 대화에서 선택하면 됩니다. Claude에게 사용할 Keboola 프로젝트를 물어보세요.

자세한 설정 안내와 리전별 URL은 원격 서버 설정 문서를 참조하세요.

개발 브랜치 사용

프로덕션 데이터에 영향을 주지 않고 Keboola 개발 브랜치에서 안전하게 작업할 수 있습니다. 원격으로 호스팅되는 MCP Server는 KBC_BRANCH_ID 매개변수를 따르며 모든 작업의 범위를 지정된 브랜치로 제한합니다. UI에서 개발 브랜치로 이동할 때 URL에서 개발 브랜치 ID를 확인할 수 있습니다. 예: https://connection.us-east4.gcp.keboola.com/admin/projects/PROJECT_ID/branch/BRANCH_ID/dashboard. 각 요청에는 X-Branch-Id: <branchId> 헤더를 사용해 브랜치 ID를 포함해야 합니다. 그렇지 않으면 MCP Server는 기본적으로 프로덕션 브랜치를 사용합니다. 이 설정은 AI 클라이언트 또는 서버 연결을 처리하는 환경에서 관리해야 합니다.

도구 권한 부여 및 액세스 제어

HTTP 기반 전송(Streamable HTTP)을 사용할 때는 HTTP 헤더를 사용해 클라이언트에서 사용할 수 있는 도구를 제어할 수 있습니다. 이는 AI 에이전트의 기능을 제한하거나 규정 준수 정책을 적용할 때 유용합니다.

권한 부여 헤더

헤더	설명	예시
X-Allowed-Tools	허용된 도구의 쉼표로 구분된 목록	get_configs,get_buckets,query_data
X-Disallowed-Tools	제외할 도구의 쉼표로 구분된 목록	create_config,run_job
X-Read-Only-Mode	읽기 전용 도구만 허용	true, 1 또는 yes

필터 동작

필터는 허용 → 읽기 전용 교집합 → 제외 순서로 적용됩니다. 헤더가 비어 있으면 제한이 없습니다.

읽기 전용 도구

읽기 전용 도구는 readOnlyHint=True 주석이 달린 도구입니다. 이 도구는 Keboola 프로젝트를 변경하지 않고 정보만 가져옵니다. 현재 읽기 전용 도구 목록은 실제 도구 집합을 자동 생성해 스냅샷으로 저장한 TOOLS.md 파일을 참조하세요.

예시: 읽기 전용 액세스

X-Read-Only-Mode: true

지연 도구 로딩

헤더	설명	예시
X-Deferred-Tools	_meta["anthropic/alwaysLoad"] = false에 나열할 도구의 쉼표로 구분된 목록	run_sync_action,get_flow_schema

서버를 alwaysLoad: true로 등록하는 Claude Code / Claude Agent SDK 클라이언트는 도구 정의를 미리 로드하는 대신 도구 검색을 통해 해당 도구를 지연 로드 상태로 유지합니다. 이 헤더는 tools/list 메타데이터만 변경하며 도구를 숨기거나 권한을 부여하지 않습니다. 헤더가 비어 있거나 알 수 없는 도구 이름이 지정되면 변경 사항이 없습니다.

자세한 내용은 developers.keboola.com/integrate/mcp/#tool-authorization-and-access-control을 참조하세요.

행 수준 및 열 수준 보안

행 수준 및 열 수준 정책은 Keboola Metastore 객체(rls-policy, cls-policy)이며, kbagent rls / kbagent cls을 사용해 작성합니다. 이 서버는 해당 정책을 읽거나 적용하지 않습니다. 프로젝트에 row-level-security 기능이 있으면 서버는 Connection 로그인 유형 governed을 사용해 작업 공간을 생성합니다 (keboola.mcp-server-tool 컴포넌트의 mcp-workspace-<hex> 구성). 관리형 작업 공간에는 자격 증명이 없습니다. Query Service만 이를 읽을 수 있으며, Query Service는 모든 query_data 결과에 프로젝트 정책을 적용해 필터링합니다. 이 서버에서는 쿼리를 다시 작성하지 않으며 대체 경로도 없습니다. Query Service가 거부하는 항목은 query_data에서 오류로 반환됩니다.

• 활성화 조건. 이 서버만 프로젝트 기능을 확인합니다. Connection은 관리형 작업 공간을 생성하는 데 기능이나 역할이 필요하지 않습니다(Snowflake 또는 BigQuery, 공개 키 없음). 스택의 Connection은 프로젝트의 백엔드에 대해 로그인 유형 governed을 허용해야 합니다. 허용하지 않는 스택에서는 생성이 거부되고, 이후 작업 공간이 필요한 모든 도구가 실패합니다(일반 작업 공간으로 대체되지 않음). 기존 일반 MCP 작업 공간은 삭제되지 않지만 기능이 활성화되면 건너뜁니다. 기능이 활성화된 상태에서는 workspace_schema 또는 X-Workspace-Id 고정 설정이 관리형 작업 공간에만 허용됩니다(일반 작업 공간은 정책을 우회해 데이터를 읽을 수 있음). 따라서 이전 작업 공간이나 데이터 앱 자체의 일반 작업 공간을 지정하면 거부됩니다. 이전 작업 공간을 삭제하세요.
• 기본적으로 거부. Query Service는 적용되는 rls-policy이 없는 관리형 작업 공간의 테이블을 거부합니다("*" 규칙은 식별된 모든 리더에게 테이블을 공개함). cls-policy만으로는 행에 대한 액세스 권한이 부여되지 않습니다. 테이블을 읽지 않는 문(SELECT 1)은 실행됩니다. 거부 결과는 에이전트에 Row-level security does not allow this query으로 전달됩니다.
• 리더 식별. Query Service는 프로젝트 관리자의 자체 토큰에서 리더를 확인합니다. 이 서버가 전달하는 프로그래밍 토큰(kbc_at_ / kbc_pat_, 다중 프로젝트 범위의 하위 PAT 포함, X-KBC-ProjectId과 함께 전송) 또는 관리자의 자체 마스터 Storage 토큰이 사용됩니다. 다른 토큰(통합, 데이터 앱, Kai)은 최종 사용자를 식별하지 않으며 검증된 ID가 없으므로 관리형 테이블에서 아무것도 읽을 수 없습니다. ID에 그룹이 포함되지 않으므로 그룹 규칙은 일치하지 않습니다.
• 바인딩. 바인딩이 없으면 작업 공간은 프로젝트의 모든 정책을 적용받으며, 이 서버는 바인딩을 생성하지 않습니다. 작업 공간에 일부 정책만 적용하려면 해당 정책을 KID에 바인딩합니다: KID:<stack id>:project-<project id>:workspace-<workspace id> (기본 브랜치의 작업 공간이며, 브랜치 작업 공간에는 branch-<branch id>도 project 앞에 있어야 함). 스택 ID는 Query Service가 구성된 ID(QUERY_RLS_STACK_ID, 예: dev-keboola-aws-eu-west-1)이며, 작업 공간 ID는 get_project_info 출력에 있습니다. kbagent rls bind --project P --workspace-id WS --rls-policy ID --stack-id S은 바인딩을 기록합니다. 바인딩은 정책 범위만 좁히고 다음 쿼리부터 적용되며, 세션을 따라 다른 작업 공간으로 이동하지 않습니다. 브랜치 세션이나 다시 생성된 작업 공간은 새 KID를 가지며 모든 정책이 다시 적용됩니다.
• 제한 사항. 별도의 작업 공간이 제공되지 않는 경우 서버 작업 공간의 ID는 데이터 앱이 WORKSPACE_ID으로 받는 ID이기도 합니다. 앱은 자체 토큰으로 쿼리하며 검증된 ID가 없으므로 관리형 테이블에서 아무것도 읽을 수 없습니다.
• 메타데이터. 메타데이터 도구에는 Query Service가 리더에게 허용하는 정보만 표시됩니다. get_tables 및 search은(는) (개수가 숨겨진 테이블까지 포함하므로 전역 검색을 사용하지 않으며) 리더가 읽을 수 없는 테이블을 제외합니다. get_tables은(는) ID로 요청한 테이블을 찾을 수 없다고 보고합니다. 열 정책이 있는 테이블에는 정책에 지정된 열만 표시됩니다(기본 키와 search의 일치 항목에도 동일하게 적용됨). 읽을 수 있는 테이블은 행 수와 크기가 표시되지 않습니다. 이 값은 행 정책으로 숨겨진 행까지 포함하기 때문입니다. get_buckets은(는) 모든 버킷을 나열하지만, 숨겨진 테이블까지 포함하는 테이블 수와 크기는 표시하지 않습니다. 이를 위해 Query Service 엔드포인트 POST /api/v1/branches/{branch}/workspaces/{workspace}/rls/scope이 필요하며, 오류 발생 시 액세스를 차단합니다. Query Service가 판단할 수 없으면 관리형 프로젝트의 도구는 짧은 메시지와 함께 오류를 반환하고 테이블은 반환하지 않습니다. 기능이 없는 프로젝트에는 영향을 주지 않으며 추가 호출도 발생하지 않습니다.

---

로컬 MCP Server 설정(사용자 지정 또는 개발 방식)

완전한 제어와 간편한 개발을 위해 MCP Server를 자신의 컴퓨터에서 실행하세요. 도구를 사용자 지정하거나, 로컬에서 디버깅하거나, 빠르게 반복 개발하려는 경우 이 방법을 선택하세요. 서버를 설치하고 인증한 다음(브라우저에서 한 번 로그인하면 되며 토큰을 붙여넣을 필요 없음) 실행하면 됩니다. 이 방식은 최대한의 유연성(사용자 지정 도구, 로컬 로깅, 오프라인 반복 개발)을 제공하지만 수동 설정이 필요하며 업데이트와 비밀 정보는 직접 관리해야 합니다. 서버는 여러 전송 옵션을 지원하며, 서버를 시작할 때 --transport <transport> 인수를 제공하여 선택할 수 있습니다.

• stdio - --transport이 지정되지 않은 경우 기본값입니다. 표준 입력/출력을 사용하며, 일반적으로 단일 클라이언트의 로컬 배포에 사용됩니다.
• streamable-http - 양방향 스트리밍 채널을 통해 HTTP로 서버를 원격 실행하여 클라이언트와 서버가 메시지를 지속적으로 주고받을 수 있습니다. /mcp로 연결합니다(예: http://localhost:8000/mcp).
• http-compat - streamable-http의 별칭이며, 이전 버전과의 호환성을 위해 유지됩니다.

Keboola 프로젝트에서 작업하려면 서버에 두 가지가 필요합니다. Keboola Region(KBC_STORAGE_API_URL)과 인증 방법입니다. 권장 방법은 브라우저에서 한 번 로그인하는 것입니다. 토큰을 만들거나 복사하거나 붙여넣을 필요가 없습니다. 선택적으로 KBC_BRANCH_ID을 설정하여 개발 브랜치에서 작업할 수 있습니다.

일부 변수는 요청 헤더에서 가져오지 않습니다.

• KBC_STORAGE_API_URL: 자체 Storage API URL(--api-url 매개변수 또는 KBC_STORAGE_API_URL 환경 변수)로 시작한 서버는 해당 Keboola 스택 하나만 제공합니다. 다른 호스트를 요청하는 X-Storage-Api-Url 헤더는 무시됩니다(경고가 기록됨). 서버는 해당 요청에 자체 URL을 계속 사용합니다. 각 요청에서 스택을 선택하도록 하려면 자체 Storage API URL 없이 서버를 시작하세요.
• KBC_KUBERNETES_TOKEN_PATH(배포된 서버만 해당, docs/kubernetes-sa-auth.md 참조): 환경 변수에서만 읽으며, 헤더에서는 읽지 않습니다.
• KBC_WORKSPACE_ID / KBC_WORKSPACE_SCHEMA: 위의 Storage API URL과 같은 방식입니다. 자체 workspace pin(두 변수 중 하나 또는 --workspace-id을 통해)을 지정하여 시작한 서버는 모든 요청에 해당 pin을 유지합니다. 다른 workspace를 요청하는 X-Workspace-Id 또는 X-Workspace-Schema 헤더는 무시됩니다(경고가 기록됨). 자체 pin이 없는 서버(공유 다중 사용자 환경)는 아래 설명처럼 요청별로 요청에서 pin을 계속 가져옵니다.

로그인

브라우저에서 한 번 로그인하면 서버가 세션을 저장하고 자동으로 갱신하므로 관리할 토큰이 없습니다.

uvx keboola_mcp_server login --api-url https://connection.YOUR_REGION.keboola.com

브라우저에서 Keboola에 로그인한 다음, 스택 전체에 적용되는 세션을 ~/.keboola/mcp/credentials.json에 저장합니다(사용자만 읽을 수 있으며 스택당 항목 하나). 이후에는 KBC_STORAGE_API_URL만 설정하여 서버를 시작하면 됩니다. 토큰은 필요하지 않습니다. 작업할 프로젝트는 로그인 중이 아니라 대화 중에(get_accessible_projects / set_project_scope) 선택합니다.

명령	기능
login --api-url <url>	스택에 로그인
login --force	다시 로그인 / 계정 전환
login --show-token	현재 세션 토큰 출력(디버깅)
logout [--api-url <url>] [--all]	스택(또는 모든 스택)에 저장된 세션 제거

저장된 세션이 없는 상태에서 대화형 터미널의 stdio로 서버를 시작하면, 첫 시작 시 브라우저 로그인이 자동으로 실행됩니다. MCP 클라이언트(Claude, Cursor, …)는 브라우저를 열 수 없는 백그라운드에서 서버를 실행하므로, 먼저 직접 login을 한 번 실행하세요.

Keboola 계정 없이 시작하기

KBC_STORAGE_API_URL만 설정하고 자격 증명 없이 서버를 시작할 수도 있습니다. 서버는 부트스트랩 모드로 실행됩니다. Keboola 액세스가 필요한 도구는 자격 증명을 얻는 방법을 안내하며, 자격 증명 없이 사용할 수 있는 도구 하나는 create_project입니다. 이 도구는 새 Keboola 프로젝트를 만들고 세션을 해당 프로젝트에 로그인한 뒤 확인 URL을 반환합니다. 브라우저에서 URL을 열고 로그인하면 프로젝트가 영구적으로 사용자 소유가 됩니다. 그때까지는 임시 프로젝트이며 Keboola가 회수할 수 있습니다. 확인이 완료되면 도구가 만든 세션은 폐기되고, 사용자는 자신의 login으로 계속 작업합니다.

이 기능을 사용하려면 에이전트 프로비저닝이 활성화된 스택이 필요합니다. 그렇지 않은 환경에서는 도구를 사용할 수 없다고 표시됩니다.

서버를 전혀 실행하지 않고도 같은 작업을 할 수 있습니다. 운영자가 기능을 활성화한 원격 호스팅 MCP 서버(KBC_ALLOW_ANONYMOUS_PROVISIONING)에서는 자격 증명을 받지 않는 https://mcp.<stack>/mcp-anonymous도 제공합니다. 인증 없이 클라이언트를 해당 서버에 연결하고 create_project을 호출한 다음, 호출로 생성된 프로젝트에서 계속 작업하면 됩니다. 서버가 사용자를 대신해 자격 증명을 보관하고, 도구는 이후 호출에서 다시 보낼 불투명한 scope_token을 반환합니다. 일반 /mcp 엔드포인트는 인증되지 않은 요청을 계속 거부해야 하므로 별도의 URL을 사용합니다. 이 거부 응답을 통해 MCP 클라이언트는 OAuth 로그인을 시작해야 한다는 것을 알 수 있습니다. 프로젝트를 소유한 뒤에는 /mcp으로 전환하고, 이제 프로젝트를 소유한 계정으로 로그인하세요.

브라우저 없이 인증하기

브라우저 로그인이 불가능한 컨테이너나 CI 환경에서는 Keboola 액세스 토큰 또는 개인 액세스 토큰을 직접 제공하세요. KBC_STORAGE_TOKEN(환경 변수)을 설정하거나 X-StorageAPI-Token 헤더를 보내고, 프로젝트를 선택하려면 KBC_PROJECT_ID(또는 X-KBC-ProjectId 헤더)도 함께 지정합니다. HTTP 전송에서는 요청별 헤더로 제공할 수 있으므로 각 요청에 자체 자격 증명을 포함할 수 있습니다.

KBC_WORKSPACE_ID

위의 스키마 기반 조회 대신 ID로 지정한 특정 기존 workspace에 쿼리를 고정하며, 둘 다 설정된 경우 KBC_WORKSPACE_SCHEMA보다 우선합니다. Data App / kai-agent 호출자가 X-Workspace-Id 헤더로 제공하는 옵션으로, 해당 앱에 포함된 Kai가 자체 workspace를 통해서만 쿼리하도록 합니다.

KBC_WORKSPACE_ID 환경 변수, --workspace-id CLI 플래그 또는 (다중 사용자 배포에서 요청별로) X-Workspace-Id 헤더를 통해 설정합니다.

KBC_STORAGE_API_URL (Keboola Region)

Keboola Region API URL은 배포 지역에 따라 다릅니다. Keboola 프로젝트에 로그인한 상태에서 브라우저의 URL을 확인하면 지역을 알 수 있습니다.

지역	API URL
AWS North America	https://connection.keboola.com
AWS Europe	https://connection.eu-central-1.keboola.com
Google Cloud EU	https://connection.europe-west3.gcp.keboola.com
Google Cloud US	https://connection.us-east4.gcp.keboola.com
Azure EU	https://connection.north-europe.azure.keboola.com

KBC_BRANCH_ID (선택 사항)

특정 Keboola 개발 브랜치에서 작업하려면 KBC_BRANCH_ID 매개변수로 브랜치 ID를 설정합니다. MCP 서버는 지정된 브랜치로 기능 범위를 제한하여 모든 변경 사항이 격리되고 프로덕션 브랜치에 영향을 주지 않도록 합니다.

• 지정하지 않으면 서버는 기본적으로 프로덕션 브랜치를 사용합니다.
• 개발 작업을 하려면 KBC_BRANCH_ID을 브랜치의 숫자 ID로 설정합니다(예: 123456). UI에서 개발 브랜치로 이동할 때 URL에 표시되는 ID를 확인할 수 있습니다. 예: https://connection.us-east4.gcp.keboola.com/admin/projects/PROJECT_ID/branch/BRANCH_ID/dashboard.
• 원격 전송에서는 HTTP 헤더 X-Branch-Id: <branchId> 또는 KBC_BRANCH_ID: <branchId>을 사용하여 요청별로 재정의할 수 있습니다.

설치

다음 항목이 있는지 확인하세요.

• Python 3.11+ 설치
• 관리자 권한이 있는 Keboola 프로젝트 액세스
• 선호하는 MCP 클라이언트(Claude, Cursor 등)

참고: uv이 설치되어 있는지 확인하세요. MCP 클라이언트는 이를 사용하여 Keboola MCP Server를 자동으로 다운로드하고 실행합니다. uv 설치:

macOS/Linux:

#if homebrew is not installed on your machine use:
# /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install using Homebrew
brew install uv

Windows:

# Using the installer script
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Or using pip
pip install uv

# Or using winget
winget install --id=astral-sh.uv -e

다른 설치 방법은 uv 공식 문서를 참조하세요.

Keboola MCP Server 실행

필요에 따라 Keboola MCP Server를 사용하는 방법은 네 가지입니다.

옵션 A: 통합 모드(권장)

이 모드에서는 Claude 또는 Cursor가 MCP 서버를 자동으로 시작합니다.

1. 세션을 저장하려면 터미널에서 한 번 로그인합니다(클라이언트는 브라우저를 열 수 없는 백그라운드에서 서버를 실행합니다).

   uvx keboola_mcp_server login --api-url https://connection.YOUR_REGION.keboola.com
   

2. 아래 설정으로 MCP 클라이언트(Claude/Cursor)를 구성합니다. KBC_STORAGE_API_URL만 필요합니다.
3. 클라이언트는 필요할 때 MCP 서버를 자동으로 실행합니다.

Claude Desktop 구성

1. Claude(화면 왼쪽 상단) -> Settings → Developer → Edit Config로 이동합니다(claude_desktop_config.json이 보이지 않으면 새로 만드세요).
2. 다음 구성을 추가합니다.
3. 변경 사항을 적용하려면 Claude desktop을 다시 시작합니다.

{
  "mcpServers": {
    "keboola": {
      "command": "uvx",
      "args": ["keboola_mcp_server --transport <transport>"],
      "env": {
        "KBC_STORAGE_API_URL": "https://connection.YOUR_REGION.keboola.com",
        "KBC_BRANCH_ID": "your_branch_id_optional"
      }
    }
  }
}

구성 파일 위치:

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

Cursor 구성

1. Settings → MCP로 이동합니다.
2. "+ Add new global MCP Server"를 클릭합니다.
3. 다음 설정을 구성합니다.

{
  "mcpServers": {
    "keboola": {
      "command": "uvx",
      "args": ["keboola_mcp_server --transport <transport>"],
      "env": {
        "KBC_STORAGE_API_URL": "https://connection.YOUR_REGION.keboola.com",
        "KBC_BRANCH_ID": "your_branch_id_optional"
      }
    }
  }
}

참고: MCP 서버에는 짧고 설명적인 이름을 사용하세요. 전체 도구 이름에는 서버 이름이 포함되며 약 60자 이하여야 하므로, 이름이 너무 길면 Cursor에서 필터링되어 Agent에 표시되지 않을 수 있습니다.

Windows WSL용 Cursor 구성

Windows Subsystem for Linux에서 Cursor AI와 함께 MCP 서버를 실행할 때는 다음 구성을 사용하세요.

{
  "mcpServers": {
    "keboola":{
      "command": "wsl.exe",
      "args": [
          "bash",
          "-c '",
          "export KBC_STORAGE_API_URL=https://connection.YOUR_REGION.keboola.com &&",
          "export KBC_BRANCH_ID=your_branch_id_optional &&",
          "/snap/bin/uvx keboola_mcp_server --transport <transport>",
          "'"
      ]
    }
  }
}

옵션 B: 로컬 개발 모드

MCP 서버 코드 자체를 개발하는 경우:

1. 저장소를 복제하고 로컬 환경을 설정합니다.
2. Claude/Cursor가 로컬 Python 경로를 사용하도록 구성합니다.

{
  "mcpServers": {
    "keboola": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": [
        "-m",
        "keboola_mcp_server --transport <transport>"
      ],
      "env": {
        "KBC_STORAGE_API_URL": "https://connection.YOUR_REGION.keboola.com",
        "KBC_BRANCH_ID": "your_branch_id_optional"
      }
    }
  }
}

옵션 C: 수동 CLI 모드(테스트 전용)

테스트 또는 디버깅을 위해 터미널에서 서버를 수동으로 실행할 수 있습니다.

# Sign in once (stores a session under ~/.keboola/mcp), then start the server.
export KBC_STORAGE_API_URL=https://connection.YOUR_REGION.keboola.com
uvx keboola_mcp_server login --api-url "$KBC_STORAGE_API_URL"

uvx keboola_mcp_server --transport streamable-http

참고: 이 모드는 주로 디버깅이나 테스트용입니다. Claude 또는 Cursor에서 일반적으로 사용할 때는 서버를 수동으로 실행할 필요가 없습니다.

참고: 서버는 Streamable HTTP 전송을 사용하며, /mcp에서 들어오는 연결을 수신하기 위해 localhost:8000을 사용합니다. --port 및 --host 매개변수를 사용하여 다른 위치에서 수신하도록 설정할 수 있습니다.

옵션 D: Docker 사용

컨테이너에서는 브라우저를 열 수 없으므로 토큰으로 인증하세요(브라우저 없이 인증하기 참조). KBC_STORAGE_TOKEN에 Keboola 액세스 토큰/개인 액세스 토큰을 설정하고, KBC_PROJECT_ID에 대상 프로젝트를 설정합니다. (HTTP에서는 대신 요청별로 X-StorageAPI-Token / X-KBC-ProjectId 헤더를 전달하고 이 변수들은 생략할 수 있습니다.)

docker pull keboola/mcp-server:latest

docker run \
  --name keboola_mcp_server \
  --rm \
  -it \
  -p 127.0.0.1:8000:8000 \
  -e KBC_STORAGE_API_URL="https://connection.YOUR_REGION.keboola.com" \
  -e KBC_STORAGE_TOKEN="YOUR_KEBOOLA_TOKEN" \
  -e KBC_PROJECT_ID="YOUR_PROJECT_ID" \
  -e KBC_BRANCH_ID="YOUR_BRANCH_ID_OPTIONAL" \
  keboola/mcp-server:latest \
  --transport streamable-http \
  --host 0.0.0.0

참고: 서버는 Streamable HTTP 전송을 사용하며, /mcp에서 들어오는 연결을 수신하기 위해 localhost:8000을 사용합니다. 컨테이너 포트를 다른 위치에 매핑하려면 -p을 변경할 수 있습니다.

서버를 직접 시작해야 하나요?

시나리오	수동 실행 필요 여부	사용할 설정
Claude/Cursor 사용	아니요	앱 설정에서 MCP 구성
MCP 로컬 개발	아니요(Claude가 시작)	구성을 Python 경로로 지정
CLI 수동 테스트	예	터미널에서 실행
Docker 사용	예	Docker 컨테이너 실행

MCP Server 사용

MCP 클라이언트(Claude/Cursor)를 구성하고 실행한 뒤에는 Keboola 데이터를 쿼리할 수 있습니다.

설정 확인

간단한 쿼리로 모든 것이 제대로 작동하는지 확인할 수 있습니다.

What buckets and tables are in my Keboola project?

수행할 수 있는 작업 예시

데이터 탐색:

• "고객 정보가 포함된 테이블은 무엇인가요?"
• "매출 기준 상위 10명의 고객을 찾는 쿼리를 실행해 주세요."

데이터 분석:

• "지난 분기 지역별 판매 데이터를 분석해 주세요."
• "고객 연령과 구매 빈도 간의 상관관계를 찾아 주세요."

데이터 파이프라인:

• "고객 테이블과 주문 테이블을 조인하는 SQL 변환을 만들어 주세요."
• "Salesforce 컴포넌트의 데이터 추출 작업을 시작해 주세요."

호환성

MCP 클라이언트 지원

MCP 클라이언트	지원 상태	연결 방법
Claude (Desktop & Web)	✅ 지원됨	stdio
Cursor	✅ 지원됨	stdio
Windsurf, Zed, Replit	✅ 지원됨	stdio
Codeium, Sourcegraph	✅ 지원됨	Streamable HTTP
사용자 지정 MCP 클라이언트	✅ 지원됨	Streamable HTTP 또는 stdio

지원되는 도구

참고: AI 에이전트는 새 도구에 자동으로 맞춰집니다.

사용 가능한 도구의 전체 목록과 자세한 설명, 매개변수 및 사용 예시는 TOOLS.md를 참조하세요.

문제 해결

일반적인 문제

문제	해결 방법
인증 오류	keboola_mcp_server login을(를) 다시 실행하거나(토큰으로 인증하는 경우 토큰과 KBC_PROJECT_ID을(를) 확인)
연결 시간 초과	네트워크 연결을 확인

개발

설치

기본 설정:

uv sync --extra dev

기본 설정으로 uv run tox을(를) 사용해 테스트를 실행하고 코드 스타일을 확인할 수 있습니다.

권장 설정:

uv sync --extra dev --extra tests --extra integtests --extra codestyle

권장 설정을 사용하면 테스트 및 코드 스타일 검사 패키지가 설치되어, VsCode 또는 Cursor와 같은 IDE에서 개발 중에 코드를 확인하거나 테스트를 실행할 수 있습니다.

통합 테스트

통합 테스트를 로컬에서 실행하려면 uv run tox -e integtests을(를) 사용하세요. 참고: 다음 환경 변수를 설정해야 합니다.

• INTEGTEST_POOL_STORAGE_API_URL
• INTEGTEST_STORAGE_TOKENS
• INTEGTEST_STORAGE_TOKEN_STORAGE_BRANCHES

이 값을 얻으려면 통합 테스트 전용 Keboola 프로젝트가 필요합니다. 각 테스트 세션은 자체 읽기 전용 워크스페이스를 생성하므로 워크스페이스 스키마를 구성할 필요가 없습니다. 자세한 설정 지침과 설계 문서는 integtests/README.md을(를) 참조하세요.

uv.lock 업데이트

종속성을 추가하거나 제거한 경우 uv.lock 파일을 업데이트하세요. 또한 릴리스를 만들 때 더 최신 종속성 버전으로 잠금 파일을 업데이트하는 것도 고려하세요(uv lock --upgrade).

도구 문서 업데이트

도구 설명(도구 함수의 독스트링)을 변경하면 변경 사항이 반영되도록 TOOLS.md 문서 파일을 다시 생성해야 합니다.

uv run python -m src.keboola_mcp_server.generate_tool_docs

릴리스

병합된 PR마다 릴리스를 만들지는 않습니다. 변경 사항은 트렁크(main)에 지속적으로 반영되며, 변경 사항을 함께 다시 테스트한 후 주기적으로 릴리스합니다. 이렇게 하면 사용자의 정상 작동 중인 설정이 깨지는 일을 방지할 수 있습니다.

릴리스는 하나 또는 두 개의 git 태그를 푸시하여 만듭니다.

• vX.Y.Z — MCP 서버 릴리스(항상)
• agent-vX.Y.Z — In Platform Agent 릴리스(에이전트도 함께 릴리스하는 경우에만)

두 태그 중 하나라도 release.yml CI를 트리거하면 Docker 이미지를 빌드하고 게시합니다. KaiBench는 프로덕션 vX.Y.Z 태그에서만 실행됩니다(agent-vX.Y.Z에서는 실행되지 않으며, -dev. 프리릴리스에서도 실행되지 않습니다). release-notes 스킬을 사용하세요. 이 스킬은 릴리스 노트와 초안 PR을 준비하고 vX.Y.Z 및 agent-vX.Y.Z 모두에 태그를 지정하는 과정을 안내합니다.

지원 및 피드백

⭐ 도움을 받거나 버그를 신고하거나 기능을 요청하려면 GitHub에서 이슈를 여는 것이 가장 기본적인 방법입니다. ⭐

개발팀은 이슈를 적극적으로 모니터링하며 가능한 한 신속하게 답변합니다. Keboola에 대한 일반 정보는 아래 리소스를 이용하세요.

리소스

• 사용자 문서
• 개발자 문서
• Keboola 플랫폼
• 이슈 트래커 ← MCP Server의 기본 연락 방법

소통

• LinkedIn
• Twitter
• 변경 로그