Keboola

Keboola MCP Server

Kết nối các tác nhân AI, ứng dụng khách MCP (Cursor, Claude, Windsurf, VS Code ...) và các trợ lý AI khác của bạn với Keboola. Cung cấp dữ liệu, phép biến đổi, truy vấn SQL và trình kích hoạt tác vụ—không cần mã kết nối. Cung cấp dữ liệu phù hợp cho các tác nhân vào đúng thời điểm và đúng nơi họ cần.

Tổng quan

Keboola MCP Server là cầu nối mã nguồn mở giữa dự án Keboola của bạn và các công cụ AI hiện đại. Công cụ này biến các tính năng của Keboola—như quyền truy cập bộ nhớ, phép biến đổi SQL và trình kích hoạt tác vụ—thành các công cụ có thể gọi cho Claude, Cursor, CrewAI, LangChain, Amazon Q và nhiều công cụ khác.

• Bắt đầu nhanh
• Thiết lập cục bộ

Tính năng

Với AI Agent và MCP Server, bạn có thể:

• Bộ nhớ: Truy vấn trực tiếp các bảng và quản lý mô tả bảng hoặc bucket
• Thành phần: Tạo, liệt kê và kiểm tra các cấu hình extractor, writer, ứng dụng dữ liệu và phép biến đổi
• SQL: Tạo phép biến đổi SQL bằng ngôn ngữ tự nhiên
• Tác vụ: Chạy các thành phần và phép biến đổi, đồng thời truy xuất thông tin chi tiết về quá trình thực thi tác vụ
• Luồng: Xây dựng và quản lý các quy trình công việc bằng Conditional Flows và Orchestrator Flows.
• Ứng dụng dữ liệu: Tạo, triển khai và quản lý Keboola Data Apps hiển thị các truy vấn của bạn trên dữ liệu bộ nhớ — ứng dụng python-js trên kho lưu trữ do Keboola quản lý hoặc trên kho lưu trữ GitHub của khách hàng (được sao chép thông qua kết nối GitHub của tổ chức, không lưu thông tin xác thực), và ứng dụng Streamlit.
• Siêu dữ liệu: Tìm kiếm, đọc và cập nhật tài liệu dự án cùng siêu dữ liệu đối tượng bằng ngôn ngữ tự nhiên
• Nhánh phát triển: Làm việc an toàn trong các nhánh phát triển, tách biệt khỏi môi trường production, nơi mọi thao tác đều được giới hạn trong nhánh đã chọn.

---

🚀 Bắt đầu nhanh: MCP Server từ xa (Cách dễ nhất)

Cách dễ nhất để sử dụng Keboola MCP Server là thông qua MCP Server từ xa. Giải pháp được lưu trữ này loại bỏ nhu cầu thiết lập, cấu hình hoặc cài đặt cục bộ.

MCP Server từ xa là gì?

Máy chủ từ xa của chúng tôi được lưu trữ trên mọi stack Keboola đa khách hàng và hỗ trợ xác thực OAuth. Bạn có thể kết nối với máy chủ này từ bất kỳ trợ lý AI nào hỗ trợ kết nối Streamable HTTP từ xa và xác thực OAuth.

Cách kết nối

1. Lấy URL máy chủ từ xa: Truy cập Cài đặt dự án Keboola → tab MCP Server
2. Sao chép URL máy chủ: URL sẽ có dạng https://mcp.<YOUR_REGION>.keboola.com/mcp
3. Cấu hình trợ lý AI: Dán URL vào phần cài đặt MCP của trợ lý AI
4. Xác thực: Bạn sẽ được yêu cầu đăng nhập bằng tài khoản Keboola. Sau đó, hãy chọn (các) dự án cần làm việc trong cuộc trò chuyện (ví dụ: "liệt kê các dự án Keboola của tôi" / "sử dụng dự án X")

Ứng dụng khách được hỗ trợ

• Cursor: Sử dụng nút "Install In Cursor" trong phần cài đặt MCP Server của dự án hoặc nhấp vào nút này
• Claude Desktop: Thêm tích hợp qua Cài đặt → Tích hợp
• Claude Code: Cài đặt bằng claude mcp add --transport http keboola <URL> (xem chi tiết bên dưới)
• Windsurf: Cấu hình bằng URL máy chủ từ xa
• Make: Cấu hình bằng URL máy chủ từ xa
• Các ứng dụng khách MCP khác: Cấu hình bằng URL máy chủ từ xa

Thiết lập Claude Code

Claude Code là công cụ giao diện dòng lệnh cho phép bạn tương tác với Claude bằng terminal. Bạn có thể cài đặt tích hợp Keboola MCP Server bằng một lệnh đơn giản.

Cài đặt:

Chạy lệnh sau trong terminal, thay <YOUR_REGION> bằng khu vực Keboola của bạn:

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

Lệnh theo khu vực:

Khu vực	Lệnh cài đặt
US Virginia AWS	claude mcp add --transport http keboola https://mcp.keboola.com/mcp
US Virginia GCP	claude mcp add --transport http keboola https://mcp.us-east4.gcp.keboola.com/mcp
EU Frankfurt AWS	claude mcp add --transport http keboola https://mcp.eu-central-1.keboola.com/mcp
EU Ireland Azure	claude mcp add --transport http keboola https://mcp.north-europe.azure.keboola.com/mcp
EU Frankfurt GCP	claude mcp add --transport http keboola https://mcp.europe-west3.gcp.keboola.com/mcp

Cách sử dụng:

Sau khi cài đặt, bạn có thể sử dụng Keboola MCP Server trong Claude Code bằng cách nhập /mcp vào cuộc trò chuyện và chọn các công cụ Keboola muốn sử dụng.

Xác thực:

Khi sử dụng Keboola MCP Server trong Claude Code lần đầu, một cửa sổ trình duyệt sẽ mở ra và yêu cầu bạn:

1. Đăng nhập bằng tài khoản Keboola
2. Cho phép kết nối

Sau khi xác thực, bạn có thể bắt đầu sử dụng trực tiếp các công cụ Keboola trong Claude Code. Việc chọn dự án diễn ra sau đó trong cuộc trò chuyện — chỉ cần hỏi Claude nên sử dụng (các) dự án Keboola nào.

Để xem hướng dẫn thiết lập chi tiết và URL theo khu vực, hãy xem tài liệu Thiết lập máy chủ từ xa.

Sử dụng nhánh phát triển

Bạn có thể làm việc an toàn trong các nhánh phát triển Keboola mà không ảnh hưởng đến dữ liệu production. MCP Server được lưu trữ từ xa tuân theo tham số KBC_BRANCH_ID và giới hạn mọi thao tác trong nhánh được chỉ định. Bạn có thể tìm ID nhánh phát triển trong URL khi mở nhánh phát triển trên giao diện người dùng, ví dụ: https://connection.us-east4.gcp.keboola.com/admin/projects/PROJECT_ID/branch/BRANCH_ID/dashboard. ID nhánh phải được đưa vào mỗi yêu cầu bằng header X-Branch-Id: <branchId>; nếu không, MCP Server sẽ mặc định sử dụng nhánh production. Việc này cần do ứng dụng khách AI hoặc môi trường quản lý kết nối máy chủ xử lý.

Phân quyền công cụ và kiểm soát truy cập

Khi sử dụng các phương thức truyền tải dựa trên HTTP (Streamable HTTP), bạn có thể kiểm soát những công cụ nào được cung cấp cho ứng dụng khách bằng header HTTP. Tính năng này hữu ích khi cần giới hạn khả năng của tác nhân AI hoặc thực thi các chính sách tuân thủ.

Header phân quyền

Header	Mô tả	Ví dụ
X-Allowed-Tools	Danh sách công cụ được phép, phân tách bằng dấu phẩy	get_configs,get_buckets,query_data
X-Disallowed-Tools	Danh sách công cụ cần loại trừ, phân tách bằng dấu phẩy	create_config,run_job
X-Read-Only-Mode	Chỉ giới hạn ở các công cụ chỉ đọc	true, 1, hoặc yes

Cách hoạt động của bộ lọc

Bộ lọc được áp dụng theo thứ tự: cho phép → giao với tập chỉ đọc → loại trừ các mục bị cấm. Header trống = không giới hạn.

Công cụ chỉ đọc

Công cụ chỉ đọc là những công cụ được đánh dấu bằng readOnlyHint=True. Các công cụ này chỉ truy xuất thông tin mà không thực hiện thay đổi nào đối với dự án Keboola của bạn. Để xem danh sách công cụ chỉ đọc hiện tại, hãy xem tệp TOOLS.md, ảnh chụp nhanh được tạo tự động từ bộ công cụ thực tế.

Ví dụ: Quyền truy cập chỉ đọc

X-Read-Only-Mode: true

Tải công cụ theo yêu cầu

Header	Mô tả	Ví dụ
X-Deferred-Tools	Danh sách công cụ cần liệt kê bằng _meta["anthropic/alwaysLoad"] = false, phân tách bằng dấu phẩy	run_sync_action,get_flow_schema

Các ứng dụng khách Claude Code / Claude Agent SDK đăng ký máy chủ bằng alwaysLoad: true sẽ giữ các công cụ này ở trạng thái trì hoãn, chỉ hiển thị qua chức năng tìm kiếm công cụ thay vì tải định nghĩa ngay từ đầu. Header này chỉ thay đổi siêu dữ liệu tools/list — không ẩn hoặc phân quyền công cụ. Header trống hoặc tên công cụ không xác định = không thay đổi.

Để xem tài liệu chi tiết, hãy truy cập developers.keboola.com/integrate/mcp/#tool-authorization-and-access-control.

Bảo mật cấp hàng và cấp cột

Các chính sách cấp hàng và cấp cột là đối tượng Keboola Metastore (rls-policy, cls-policy), được tạo bằng kbagent rls / kbagent cls. Máy chủ này không đọc cũng không áp dụng các chính sách đó. Trong dự án có tính năng row-level-security, máy chủ tạo workspace của mình (cấu hình mcp-workspace-<hex> của thành phần keboola.mcp-server-tool) với loại đăng nhập Connection governed. Workspace được quản lý không có thông tin xác thực: chỉ Query Service mới có thể đọc workspace này, và Query Service lọc mọi kết quả query_data theo các chính sách của dự án. Máy chủ này không viết lại truy vấn và không có phương án dự phòng: nếu Query Service từ chối, query_data sẽ trả về lỗi.

• Điều kiện kích hoạt. Chỉ máy chủ này kiểm tra tính năng của dự án; Connection không cần tính năng hay vai trò nào để tạo workspace được quản lý (Snowflake hoặc BigQuery, không có khóa công khai). Connection của stack phải chấp nhận loại đăng nhập governed cho backend của dự án: nếu stack không chấp nhận, thao tác tạo sẽ bị từ chối và mọi công cụ cần workspace đều thất bại (không có phương án dự phòng dùng workspace thông thường). Workspace MCP thông thường cũ không bị xóa: khi tính năng được bật, workspace đó sẽ bị bỏ qua. Khi tính năng được bật, chỉ chấp nhận ghim workspace_schema hoặc X-Workspace-Id vào workspace được quản lý (workspace thông thường sẽ đọc vượt qua các chính sách), vì vậy việc ghim vào workspace cũ hoặc workspace thông thường riêng của ứng dụng dữ liệu sẽ bị từ chối; hãy xóa workspace cũ.
• Mặc định từ chối. Query Service từ chối bảng trong workspace được quản lý nếu không có rls-policy nào áp dụng (quy tắc "*" mở bảng cho mọi người đọc đã được xác định danh tính); chỉ có cls-policy thì không cấp quyền đọc hàng nào. Câu lệnh không đọc bảng nào (SELECT 1) vẫn chạy. Tác nhân sẽ nhận được thông báo từ chối dưới dạng Row-level security does not allow this query.
• Ai là người đọc. Query Service xác định người đọc từ token riêng của quản trị viên trong dự án: token lập trình mà máy chủ này chuyển tiếp (kbc_at_ / kbc_pat_, bao gồm PAT con của phạm vi nhiều dự án, được gửi cùng X-KBC-ProjectId) hoặc token Storage master riêng của quản trị viên. Mọi token khác (tích hợp, ứng dụng dữ liệu, Kai) không xác định người dùng cuối, không có danh tính đã xác minh và không thể đọc dữ liệu từ bảng được quản lý. Quy tắc nhóm không bao giờ khớp (danh tính không có nhóm).
• Liên kết. Nếu không có liên kết, workspace nhận mọi chính sách của dự án và máy chủ này không bao giờ tạo liên kết. Để chỉ cấp cho workspace một số chính sách nhất định, hãy liên kết chúng với KID của workspace: KID:<stack id>:project-<project id>:workspace-<workspace id> (workspace của nhánh mặc định; workspace của nhánh khác cũng cần có branch-<branch id> trước project). ID stack là ID được Query Service cấu hình sử dụng (QUERY_RLS_STACK_ID, ví dụ dev-keboola-aws-eu-west-1), ID workspace nằm trong đầu ra get_project_info, và kbagent rls bind --project P --workspace-id WS --rls-policy ID --stack-id S ghi liên kết. Liên kết chỉ thu hẹp phạm vi, có hiệu lực từ truy vấn tiếp theo và không đi theo phiên sang workspace khác: phiên của nhánh hoặc workspace được tạo lại sẽ có KID mới và bắt đầu lại với mọi chính sách.
• Giới hạn. ID workspace của máy chủ cũng là giá trị mà ứng dụng dữ liệu nhận được dưới dạng WORKSPACE_ID khi không cấp workspace riêng cho ứng dụng; ứng dụng truy vấn bằng token riêng, không có danh tính đã xác minh và không thể đọc dữ liệu từ các bảng được quản lý.
• Siêu dữ liệu. Các công cụ siêu dữ liệu chỉ hiển thị những gì Query Service cho phép người đọc xem. get_tables và search (khi đó không sử dụng tìm kiếm toàn cục vì số lượng của tìm kiếm này bao gồm cả các bảng bị ẩn) sẽ bỏ qua bảng mà người đọc không được phép đọc, còn get_tables báo không tìm thấy bảng được yêu cầu theo ID; bảng có chính sách cột chỉ hiển thị các cột được chính sách cho phép (bao gồm cả khóa chính và các cột được search đối chiếu). Bảng có thể đọc sẽ không hiển thị số hàng và dung lượng, vì các giá trị này tính cả những hàng bị chính sách hàng ẩn. get_buckets vẫn liệt kê mọi bucket nhưng không hiển thị số bảng và dung lượng, vì các giá trị này tính cả những bảng bị ẩn. Tính năng này cần endpoint Query Service POST /api/v1/branches/{branch}/workspaces/{workspace}/rls/scope và hoạt động theo nguyên tắc đóng khi có lỗi: nếu Query Service không thể xác định, công cụ của dự án được quản lý sẽ trả về lỗi với thông báo ngắn và không có bảng. Dự án không bật tính năng này không bị ảnh hưởng và không phát sinh thêm lệnh gọi.

---

Thiết lập MCP Server cục bộ (Tùy chỉnh hoặc Phát triển)

Chạy MCP server trên máy của bạn để toàn quyền kiểm soát và dễ dàng phát triển. Hãy chọn cách này nếu bạn muốn tùy chỉnh công cụ, gỡ lỗi cục bộ hoặc lặp lại nhanh chóng. Bạn sẽ cài đặt máy chủ, xác thực (đăng nhập một lần qua trình duyệt — không cần dán token) rồi khởi chạy. Cách này mang lại sự linh hoạt tối đa (công cụ tùy chỉnh, ghi nhật ký cục bộ, lặp lại ngoại tuyến), nhưng cần thiết lập thủ công và bạn phải tự quản lý các bản cập nhật cũng như thông tin bí mật. Máy chủ hỗ trợ nhiều tùy chọn truyền tải, có thể chọn bằng cách cung cấp đối số --transport <transport> khi khởi động máy chủ:

• stdio - Mặc định nếu không chỉ định --transport. Đầu vào/đầu ra tiêu chuẩn, thường dùng để triển khai cục bộ với một máy khách.
• streamable-http - Chạy máy chủ từ xa qua HTTP với kênh truyền phát hai chiều, cho phép máy khách và máy chủ liên tục trao đổi thông điệp. Kết nối qua /mcp (ví dụ: http://localhost:8000/mcp).
• http-compat - Bí danh của streamable-http, được giữ lại để tương thích ngược.

Để làm việc với dự án Keboola của bạn, máy chủ cần hai thông tin: Khu vực Keboola của bạn (KBC_STORAGE_API_URL) và phương thức xác thực. Cách được khuyến nghị là đăng nhập một lần bằng trình duyệt — bạn không cần tạo, sao chép hay dán mã thông báo. Bạn có thể tùy chọn đặt KBC_BRANCH_ID để làm việc trong một nhánh phát triển.

Một số biến không được lấy từ tiêu đề yêu cầu:

• KBC_STORAGE_API_URL: máy chủ được khởi chạy với URL Storage API riêng (tham số --api-url hoặc biến môi trường KBC_STORAGE_API_URL) chỉ phục vụ một ngăn xếp Keboola đó. Tiêu đề X-Storage-Api-Url yêu cầu một máy chủ khác sẽ bị bỏ qua (có ghi nhật ký cảnh báo) — máy chủ tiếp tục dùng URL riêng cho yêu cầu đó. Hãy khởi chạy máy chủ mà không có URL Storage API riêng nếu bạn muốn mỗi yêu cầu tự chọn ngăn xếp.
• KBC_KUBERNETES_TOKEN_PATH (chỉ máy chủ đã triển khai, xem docs/kubernetes-sa-auth.md): chỉ đọc từ môi trường, không bao giờ đọc từ tiêu đề.
• KBC_WORKSPACE_ID / KBC_WORKSPACE_SCHEMA: tương tự URL Storage API ở trên — máy chủ được khởi chạy với ghim không gian làm việc riêng (qua một trong hai biến hoặc --workspace-id) sẽ giữ nguyên ghim đó cho mọi yêu cầu; tiêu đề X-Workspace-Id hoặc X-Workspace-Schema yêu cầu không gian làm việc khác sẽ bị bỏ qua (có ghi nhật ký cảnh báo). Máy chủ không có ghim riêng (trường hợp dùng chung nhiều người dùng) tiếp tục lấy ghim từ từng yêu cầu, như mô tả bên dưới.

Đăng nhập

Đăng nhập một lần bằng trình duyệt; máy chủ lưu phiên và tự động làm mới phiên, vì vậy bạn không cần quản lý mã thông báo:

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

Thao tác này mở trình duyệt để bạn đăng nhập vào Keboola, sau đó lưu phiên dùng chung cho toàn bộ ngăn xếp vào ~/.keboola/mcp/credentials.json (chỉ bạn có thể đọc, mỗi ngăn xếp có một mục). Sau đó, khởi chạy máy chủ chỉ với KBC_STORAGE_API_URL được đặt — không cần mã thông báo. Bạn sẽ chọn dự án cần làm việc sau đó, trong cuộc trò chuyện (get_accessible_projects / set_project_scope), chứ không phải trong lúc đăng nhập.

Lệnh	Chức năng
login --api-url <url>	Đăng nhập vào một ngăn xếp
login --force	Đăng nhập lại / chuyển tài khoản
login --show-token	In mã thông báo phiên hiện tại (gỡ lỗi)
logout [--api-url <url>] [--all]	Xóa phiên đã lưu cho một ngăn xếp (hoặc tất cả các ngăn xếp)

Khi bạn khởi chạy máy chủ qua stdio trong một thiết bị đầu cuối tương tác mà chưa có phiên được lưu, máy chủ sẽ tự động thực hiện đăng nhập bằng trình duyệt trong lần khởi chạy đầu tiên. Các máy khách MCP (Claude, Cursor, …) khởi chạy máy chủ ở chế độ nền, nơi trình duyệt không thể mở; vì vậy, trước tiên hãy tự chạy login một lần.

Khởi chạy mà không cần tài khoản Keboola

Bạn cũng có thể khởi chạy máy chủ chỉ với KBC_STORAGE_API_URL và hoàn toàn không cần thông tin xác thực. Máy chủ sẽ chạy ở chế độ khởi tạo: các công cụ cần truy cập Keboola sẽ hướng dẫn cách lấy thông tin xác thực, còn một công cụ có thể hoạt động mà không cần thông tin này — create_project. Công cụ này tạo một dự án Keboola mới, đăng nhập phiên vào dự án đó và trả về URL xác nhận. Mở URL đó trong trình duyệt và đăng nhập để dự án chính thức thuộc về bạn; trước thời điểm đó, dự án chỉ là tạm thời và Keboola có thể thu hồi. Sau khi bạn xác nhận, phiên do công cụ tạo sẽ bị thu hồi và bạn tiếp tục bằng login của riêng mình.

Tính năng này yêu cầu một ngăn xếp đã bật tính năng cấp phát tác nhân; nếu không, công cụ sẽ thông báo rằng tính năng này không khả dụng.

Bạn cũng có thể thực hiện tương tự mà không cần chạy máy chủ, bằng cách dùng máy chủ MCP được lưu trữ từ xa mà đơn vị vận hành đã bật tính năng này (KBC_ALLOW_ANONYMOUS_PROVISIONING): bản triển khai đó cũng cung cấp https://mcp.<stack>/mcp-anonymous, không yêu cầu thông tin xác thực. Trỏ máy khách đến đó mà không cần xác thực, gọi create_project rồi tiếp tục làm việc trong dự án được tạo bởi lệnh gọi đó — máy chủ giữ thông tin xác thực cho bạn và công cụ trả về một scope_token không thể đọc được để gửi lại trong các lần gọi sau. URL này tách biệt vì điểm cuối /mcp thông thường phải tiếp tục từ chối các yêu cầu chưa xác thực: việc từ chối đó giúp máy khách MCP biết cần bắt đầu đăng nhập OAuth. Sau khi nhận quyền sở hữu dự án, hãy chuyển sang /mcp và đăng nhập bằng tài khoản hiện sở hữu dự án.

Xác thực không cần trình duyệt

Đối với container hoặc CI không thể đăng nhập bằng trình duyệt, hãy cung cấp trực tiếp mã thông báo truy cập hoặc mã thông báo truy cập cá nhân của Keboola — đặt KBC_STORAGE_TOKEN (biến môi trường) hoặc gửi tiêu đề X-StorageAPI-Token — cùng với KBC_PROJECT_ID (hoặc tiêu đề X-KBC-ProjectId) để chọn dự án. Với các phương thức truyền tải HTTP, bạn có thể cung cấp các giá trị này theo từng yêu cầu dưới dạng tiêu đề, nhờ đó mỗi yêu cầu mang thông tin xác thực riêng.

KBC_WORKSPACE_ID

Ghim các truy vấn vào một không gian làm việc cụ thể, đã tồn tại, bằng ID của không gian đó thay vì tra cứu dựa trên lược đồ như mô tả ở trên. Giá trị này được ưu tiên hơn KBC_WORKSPACE_SCHEMA nếu cả hai cùng được đặt. Đây là tùy chọn mà ứng dụng Data App / bên gọi kai-agent cung cấp dưới dạng tiêu đề X-Workspace-Id, để Kai được nhúng trong ứng dụng đó chỉ truy vấn thông qua không gian làm việc riêng của ứng dụng.

Đặt bằng biến môi trường KBC_WORKSPACE_ID, cờ CLI --workspace-id hoặc (theo từng yêu cầu, trong các bản triển khai nhiều người dùng) tiêu đề X-Workspace-Id.

KBC_STORAGE_API_URL (Khu vực Keboola)

URL API của Khu vực Keboola phụ thuộc vào khu vực triển khai của bạn. Bạn có thể xác định khu vực bằng cách xem URL trong trình duyệt khi đăng nhập vào dự án Keboola:

Khu vực	URL API
AWS Bắc Mỹ	https://connection.keboola.com
AWS Châu Âu	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 (Tùy chọn)

Để thao tác trên một nhánh phát triển Keboola cụ thể, hãy đặt ID nhánh bằng tham số KBC_BRANCH_ID. Máy chủ MCP giới hạn phạm vi chức năng ở nhánh được chỉ định, đảm bảo mọi thay đổi được cô lập và không ảnh hưởng đến nhánh production.

• Nếu không cung cấp, máy chủ mặc định sử dụng nhánh production.
• Để phát triển, hãy đặt KBC_BRANCH_ID thành ID dạng số của nhánh (ví dụ: 123456). Bạn có thể tìm ID nhánh phát triển trong URL khi mở nhánh đó trên giao diện người dùng, chẳng hạn: https://connection.us-east4.gcp.keboola.com/admin/projects/PROJECT_ID/branch/BRANCH_ID/dashboard.
• Với các phương thức truyền tải từ xa, bạn có thể ghi đè theo từng yêu cầu bằng tiêu đề HTTP X-Branch-Id: <branchId> hoặc KBC_BRANCH_ID: <branchId>.

Cài đặt

Đảm bảo bạn có:

• Đã cài đặt Python 3.11+
• Quyền truy cập vào một dự án Keboola với quyền quản trị
• Máy khách MCP bạn muốn dùng (Claude, Cursor, v.v.)

Lưu ý: Đảm bảo bạn đã cài đặt uv. Máy khách MCP sẽ dùng công cụ này để tự động tải xuống và chạy Keboola MCP Server. Cài đặt 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

Để xem thêm các tùy chọn cài đặt, hãy tham khảo tài liệu chính thức của uv.

Chạy Keboola MCP Server

Có bốn cách sử dụng Keboola MCP Server, tùy theo nhu cầu của bạn:

Tùy chọn A: Chế độ tích hợp (Khuyến nghị)

Ở chế độ này, Claude hoặc Cursor sẽ tự động khởi chạy máy chủ MCP cho bạn.

1. Đăng nhập một lần trong thiết bị đầu cuối để lưu phiên (máy khách khởi chạy máy chủ ở chế độ nền, nơi trình duyệt không thể mở):

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

2. Cấu hình máy khách MCP (Claude/Cursor) theo các thiết lập bên dưới — chỉ cần KBC_STORAGE_API_URL.
3. Máy khách sẽ tự động khởi chạy máy chủ MCP khi cần.

Cấu hình Claude Desktop

1. Mở Claude (góc trên bên trái màn hình) -> Settings → Developer → Edit Config (nếu không thấy claude_desktop_config.json, hãy tạo tệp này)
2. Thêm cấu hình sau:
3. Khởi động lại Claude desktop để áp dụng thay đổi

{
  "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"
      }
    }
  }
}

Vị trí tệp cấu hình:

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

Cấu hình Cursor

1. Mở Settings → MCP
2. Nhấp vào "+ Add new global MCP Server"
3. Cấu hình bằng các thiết lập sau:

{
  "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"
      }
    }
  }
}

Lưu ý: Dùng tên ngắn gọn, dễ mô tả cho máy chủ MCP. Vì tên công cụ đầy đủ bao gồm tên máy chủ và phải ngắn hơn khoảng 60 ký tự, tên dài hơn có thể bị Cursor lọc và không hiển thị cho Agent.

Cấu hình Cursor cho Windows WSL

Khi chạy máy chủ MCP từ Windows Subsystem for Linux với Cursor AI, hãy dùng cấu hình sau:

{
  "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>",
          "'"
      ]
    }
  }
}

Tùy chọn B: Chế độ phát triển cục bộ

Dành cho nhà phát triển làm việc trực tiếp trên mã của máy chủ MCP:

1. Sao chép kho lưu trữ và thiết lập môi trường cục bộ
2. Cấu hình Claude/Cursor để dùng đường dẫn Python cục bộ của bạn:

{
  "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"
      }
    }
  }
}

Tùy chọn C: Chế độ CLI thủ công (Chỉ để kiểm thử)

Bạn có thể chạy máy chủ thủ công trong thiết bị đầu cuối để kiểm thử hoặc gỡ lỗi:

# 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

Lưu ý: Chế độ này chủ yếu dành cho gỡ lỗi hoặc kiểm thử. Khi sử dụng Claude hoặc Cursor bình thường, bạn không cần chạy máy chủ thủ công.

Lưu ý: Máy chủ sẽ dùng phương thức truyền tải Streamable HTTP và lắng nghe kết nối đến tại /mcp trên localhost:8000. Bạn có thể dùng các tham số --port và --host để thay đổi địa chỉ lắng nghe.

Tùy chọn D: Dùng Docker

Container không thể mở trình duyệt, vì vậy hãy xác thực bằng mã thông báo (xem Xác thực không cần trình duyệt): đặt KBC_STORAGE_TOKEN thành mã thông báo truy cập/mã thông báo truy cập cá nhân của Keboola và KBC_PROJECT_ID thành dự án đích. (Với HTTP, bạn có thể thay vào đó truyền tiêu đề X-StorageAPI-Token / X-KBC-ProjectId theo từng yêu cầu và bỏ qua các giá trị này.)

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

Lưu ý: Máy chủ sẽ dùng phương thức truyền tải Streamable HTTP và lắng nghe kết nối đến tại /mcp trên localhost:8000. Bạn có thể thay đổi -p để ánh xạ cổng của container sang một vị trí khác.

Tôi có cần tự khởi chạy máy chủ không?

Tình huống	Có cần chạy thủ công không?	Dùng thiết lập này
Dùng Claude/Cursor	Không	Cấu hình MCP trong phần cài đặt ứng dụng
Phát triển MCP cục bộ	Không (Claude sẽ khởi chạy)	Trỏ cấu hình đến đường dẫn Python
Kiểm thử CLI thủ công	Có	Chạy trong thiết bị đầu cuối
Dùng Docker	Có	Chạy container docker

Sử dụng MCP Server

Sau khi cấu hình và khởi chạy máy khách MCP (Claude/Cursor), bạn có thể bắt đầu truy vấn dữ liệu Keboola:

Xác minh thiết lập

Bạn có thể bắt đầu bằng một truy vấn đơn giản để xác nhận mọi thứ hoạt động:

What buckets and tables are in my Keboola project?

Ví dụ về những việc bạn có thể làm

Khám phá dữ liệu:

• "Những bảng nào chứa thông tin khách hàng?"
• "Chạy truy vấn để tìm 10 khách hàng có doanh thu cao nhất"

Phân tích dữ liệu:

• "Phân tích dữ liệu bán hàng theo khu vực trong quý vừa qua"
• "Tìm mối tương quan giữa tuổi khách hàng và tần suất mua hàng"

Quy trình dữ liệu:

• "Tạo một phép biến đổi SQL kết hợp bảng khách hàng và đơn hàng"
• "Khởi chạy tác vụ trích xuất dữ liệu cho thành phần Salesforce của tôi"

Khả năng tương thích

Hỗ trợ máy khách MCP

Máy khách MCP	Trạng thái hỗ trợ	Phương thức kết nối
Claude (Desktop & Web)	✅ được hỗ trợ	stdio
Cursor	✅ được hỗ trợ	stdio
Windsurf, Zed, Replit	✅ Được hỗ trợ	stdio
Codeium, Sourcegraph	✅ Được hỗ trợ	Streamable HTTP
Máy khách MCP tùy chỉnh	✅ Được hỗ trợ	Streamable HTTP hoặc stdio

Công cụ được hỗ trợ

Lưu ý: Các tác nhân AI của bạn sẽ tự động thích ứng với các công cụ mới.

Để xem danh sách đầy đủ các công cụ hiện có cùng mô tả chi tiết, tham số và ví dụ sử dụng, hãy xem TOOLS.md.

Khắc phục sự cố

Các vấn đề thường gặp

Vấn đề	Giải pháp
Lỗi xác thực	Chạy lại keboola_mcp_server login (hoặc, nếu xác thực bằng token, hãy xác minh token và KBC_PROJECT_ID)
Hết thời gian chờ kết nối	Kiểm tra kết nối mạng

Phát triển

Cài đặt

Thiết lập cơ bản:

uv sync --extra dev

Với thiết lập cơ bản, bạn có thể dùng uv run tox để chạy kiểm thử và kiểm tra kiểu mã.

Thiết lập được khuyến nghị:

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

Với thiết lập được khuyến nghị, các gói phục vụ kiểm thử và kiểm tra kiểu mã sẽ được cài đặt, cho phép các IDE như VsCode hoặc Cursor kiểm tra mã hoặc chạy kiểm thử trong quá trình phát triển.

Kiểm thử tích hợp

Để chạy kiểm thử tích hợp cục bộ, hãy dùng uv run tox -e integtests. LƯU Ý: Bạn cần thiết lập các biến môi trường sau:

• INTEGTEST_POOL_STORAGE_API_URL
• INTEGTEST_STORAGE_TOKENS
• INTEGTEST_STORAGE_TOKEN_STORAGE_BRANCHES

Để lấy các giá trị này, bạn cần có các dự án Keboola dành riêng cho kiểm thử tích hợp. Mỗi phiên kiểm thử tạo một không gian làm việc chỉ đọc riêng, vì vậy không cần cấu hình lược đồ không gian làm việc. Xem integtests/README.md để biết hướng dẫn thiết lập chi tiết và tài liệu thiết kế.

Cập nhật uv.lock

Cập nhật tệp uv.lock nếu bạn đã thêm hoặc xóa các phần phụ thuộc. Ngoài ra, hãy cân nhắc cập nhật tệp khóa lên các phiên bản phụ thuộc mới hơn khi tạo bản phát hành (uv lock --upgrade).

Cập nhật tài liệu công cụ

Khi thay đổi mô tả của bất kỳ công cụ nào (docstring trong các hàm công cụ), bạn phải tạo lại tệp tài liệu TOOLS.md để phản ánh những thay đổi này:

uv run python -m src.keboola_mcp_server.generate_tool_docs

Phát hành

Chúng tôi không phát hành mỗi khi có PR được hợp nhất. Các thay đổi liên tục được đưa vào nhánh chính (main) và chúng tôi phát hành định kỳ sau khi kiểm thử lại các thay đổi cùng nhau — điều này giúp tránh làm hỏng các thiết lập đang hoạt động của người dùng.

Bản phát hành được tạo bằng cách đẩy một hoặc hai thẻ git:

• vX.Y.Z — bản phát hành máy chủ MCP (luôn luôn)
• agent-vX.Y.Z — bản phát hành In Platform Agent (chỉ khi agent cũng được phát hành)

Mỗi thẻ đều kích hoạt CI release.yml, quy trình này xây dựng và phát hành ảnh Docker. KaiBench chỉ chạy trên các thẻ vX.Y.Z phát hành chính thức (không chạy trên agent-vX.Y.Z hoặc các bản phát hành trước -dev.). Hãy dùng kỹ năng release-notes — kỹ năng này chuẩn bị ghi chú phát hành và PR nháp, đồng thời hướng dẫn quy trình gắn thẻ cho cả vX.Y.Z và agent-vX.Y.Z.

Hỗ trợ và phản hồi

⭐ Cách chính để nhận trợ giúp, báo lỗi hoặc yêu cầu tính năng là mở một issue trên GitHub. ⭐

Nhóm phát triển thường xuyên theo dõi các issue và sẽ phản hồi sớm nhất có thể. Để biết thông tin chung về Keboola, vui lòng sử dụng các tài nguyên bên dưới.

Tài nguyên

• Tài liệu người dùng
• Tài liệu dành cho nhà phát triển
• Nền tảng Keboola
• Trình theo dõi issue ← Phương thức liên hệ chính về MCP Server

Kết nối

• LinkedIn
• Twitter
• Nhật ký thay đổi