Keboola

Máy chủ MCP Keboola

Kết nối các tác nhân AI, máy khách MCP (Cursor, Claude, Windsurf, VS Code ...) và các trợ lý AI khác của bạn với Keboola. Truy cập dữ liệu, chuyển đổi, truy vấn SQL và kích hoạt công việc—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 khi và nơi họ cần.

Tổng quan

Máy chủ MCP Keboola 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. Nó biến các tính năng của Keboola—như truy cập lưu trữ, chuyển đổi SQL và kích hoạt công việc—thành các công cụ có thể gọi được cho Claude, Cursor, CrewAI, LangChain, Amazon Q và nhiều hơn nữa.

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

Tính năng

Với Tác nhân AI và Máy chủ MCP, bạn có thể:

• Lưu trữ: Truy vấn bảng trực tiếp và quản lý mô tả bảng hoặc nhóm bảng
• Thành phần: Tạo, liệt kê và kiểm tra các bộ trích xuất, bộ ghi, ứng dụng dữ liệu và cấu hình chuyển đổi
• SQL: Tạo chuyển đổi SQL bằng ngôn ngữ tự nhiên
• Công việc: Chạy các thành phần và chuyển đổi, đồng thời truy xuất chi tiết thực thi công việc
• Luồng: Xây dựng và quản lý các quy trình làm việc bằng Luồng có điều kiện và Luồng điều phối.
• Ứng dụng dữ liệu: Tạo, triển khai và quản lý các Ứng dụng dữ liệu Streamlit của Keboola hiển thị các truy vấn của bạn trên dữ liệu lưu trữ.
• Siêu dữ liệu: Tìm kiếm, đọc và cập nhật tài liệu dự án và 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 ngoài môi trường sản xuất, nơi tất cả các thao tác được giới hạn trong nhánh đã chọn.

---

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

Cách dễ nhất để sử dụng Máy chủ MCP Keboola là thông qua Máy chủ MCP từ xa của chúng tôi. Giải pháp 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ộ.

Máy chủ MCP từ xa là gì?

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

Cách kết nối

1. Lấy URL máy chủ từ xa của bạn: Điều hướng đến Cài đặt dự án Keboola của bạn → tab MCP Server
2. Sao chép URL máy chủ: Nó sẽ trông giống như https://mcp.<YOUR_REGION>.keboola.com/mcp
3. Cấu hình trợ lý AI của bạn: Dán URL vào cài đặt MCP của trợ lý AI
4. Xác thực: Bạn sẽ được nhắc đăng nhập bằng tài khoản Keboola của mình. (Các) dự án để làm việc được chọn sau đó, 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")

Máy khách được hỗ trợ

• Cursor: Sử dụng nút "Cài đặt trong Cursor" trong cài đặt Máy chủ MCP 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 bên dưới để biết chi tiết)
• Windsurf: Cấu hình với URL máy chủ từ xa
• Make: Cấu hình với URL máy chủ từ xa
• Máy khách MCP khác: Cấu hình với URL máy chủ từ xa

Thiết lập Claude Code

Claude Code là một công cụ giao diện dòng lệnh cho phép bạn tương tác với Claude bằng thiết bị đầu cuối của mình. Bạn có thể cài đặt tích hợp Máy chủ MCP Keboola bằng một lệnh đơn giản.

Cài đặt:

Chạy lệnh sau trong thiết bị đầu cuối của bạn, thay thế <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 cụ thể:

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 Máy chủ MCP Keboola trong Claude Code bằng cách gõ /mcp trong cuộc trò chuyện của bạn và chọn các công cụ Keboola bạn muốn sử dụng.

Xác thực:

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

1. Đăng nhập bằng tài khoản Keboola của bạn
2. Ủy quyền kết nối

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

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

Sử dụng các 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 sản xuất của mình. Các Máy chủ MCP được lưu trữ từ xa tôn trọng tham số KBC_BRANCH_ID và sẽ giới hạn tất cả các thao tác trong nhánh được chỉ định. Bạn có thể tìm thấy ID nhánh phát triển trong URL khi điều hướng đến nhánh phát triển trong 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 bao gồm trong mỗi yêu cầu bằng tiêu đề X-Branch-Id: <branchId>, nếu không Máy chủ MCP sử dụng nhánh sản xuất làm mặc định. Việc này nên được quản lý bởi máy khách AI hoặc môi trường xử lý kết nối máy chủ.

Ủy 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 các công cụ nào có sẵn cho máy khách bằng tiêu đề HTTP. Điều này hữu ích để hạn chế khả năng của tác nhân AI hoặc thực thi các chính sách tuân thủ.

Tiêu đề ủy quyền

Tiêu đề	Mô tả	Ví dụ
X-Allowed-Tools	Danh sách các 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ác 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

Hành vi lọc

Bộ lọc áp dụng theo thứ tự: được phép → giao điểm chỉ đọc → loại trừ không được phép. Tiêu đề trống = không hạn chế.

Công cụ chỉ đọc

Các công cụ chỉ đọc là những công cụ được chú thích 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 bất kỳ thay đổi nào đối với dự án Keboola của bạn. Để biết danh sách hiện tại của các công cụ chỉ đọc, hãy xem tệp TOOLS.md, đây là ảnh chụp nhanh được tạo tự động của bộ công cụ thực tế.

Ví dụ: Truy cập chỉ đọc

X-Read-Only-Mode: true

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

---

Thiết lập máy chủ MCP cục bộ (Cách tùy chỉnh hoặc dành cho nhà phát triển)

Chạy máy chủ MCP trên máy của riêng bạn để kiểm soát hoàn toàn và phát triển dễ dàng. Chọn cách này khi 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 trình duyệt một lần—không cần dán mã thông báo) và khởi động nó. Cách tiếp cận 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 yêu cầu thiết lập thủ công và bạn tự quản lý các bản cập nhật và bí mật.

Máy chủ hỗ trợ nhiều tùy chọn truyền tải, có thể được chọn bằng cách cung cấp đối số --transport <transport> khi khởi động máy chủ:

• stdio - Mặc định khi --transport không được chỉ định. Đầu vào/đầu ra tiêu chuẩn, thường được sử dụng để triển khai cục bộ với một máy khách duy nhất.
• streamable-http - Chạy máy chủ từ xa qua HTTP với kênh phát trực tuyến hai chiều, cho phép máy khách và máy chủ trao đổi tin nhắn liên tục. Kết nối qua /mcp (ví dụ: http://localhost:8000/mcp).
• http-compat - Một bí danh cho streamable-http, được giữ để 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ứ: Khu vực Keboola của bạn (KBC_STORAGE_API_URL) và một cách để xác thực. Cách được khuyến nghị là đăng nhập trình duyệt một lần—bạn không bao giờ tạo, sao chép hoặc dán mã thông báo. 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ột máy chủ được khởi động với URL API lưu trữ riêng của nó (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 đó. Một tiêu đề X-Storage-Api-Url yêu cầu một máy chủ khác sẽ bị bỏ qua (một cảnh báo được ghi lại)—máy chủ giữ URL riêng của nó cho yêu cầu. Khởi động máy chủ mà không có URL API lưu trữ riêng nếu bạn muốn mỗi yêu cầu chọn ngăn xếp của nó.
• 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ờ từ tiêu đề.
• KBC_WORKSPACE_ID / KBC_WORKSPACE_SCHEMA: cùng ý tưởng như URL API lưu trữ ở trên—một máy chủ được khởi động với khóa không gian làm việc riêng của nó (qua một trong hai biến hoặc --workspace-id) giữ khóa đó cho mọi yêu cầu; một tiêu đề X-Workspace-Id hoặc X-Workspace-Schema yêu cầu một không gian làm việc khác sẽ bị bỏ qua (một cảnh báo được ghi lại). Một máy chủ không có khóa riêng (trường hợp dùng chung nhiều người dùng) tiếp tục lấy khóa từ yêu cầu, theo từng yêu cầu, như được mô tả bên dưới.

Đăng nhập

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

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

Thao tác này mở trình duyệt của bạn để đăng nhập vào Keboola, sau đó lưu phiên toàn ngăn xếp vào ~/.keboola/mcp/credentials.json (chỉ bạn có thể đọc, một mục cho mỗi ngăn xếp). Sau đó, khởi động máy chủ chỉ với KBC_STORAGE_API_URL được đặt—không cần mã thông báo. (Các) dự án để làm việc được chọn sau đó, trong cuộc trò chuyện (get_accessible_projects / set_project_scope), 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 động máy chủ qua stdio trong một thiết bị đầu cuối tương tác mà không có phiên đã lưu, nó sẽ tự động chạy đăng nhập trình duyệt này ở lần khởi động đầu tiên. Các máy khách MCP (Claude, Cursor, …) khởi chạy máy chủ trong nền nơi trình duyệt không thể mở, vì vậy hãy chạy login một lần trước.

Bắt đầu mà không có tài khoản Keboola

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

Điều này cần một ngăn xếp có cấp phát tác nhân được bật; ở những nơi khác, công cụ báo cáo rằng nó không khả dụng.

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

Đối với các container hoặc CI nơi đăng nhập trình duyệt không thể thực hiện, hãy cung cấ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 trực tiếp—đặ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. Trên các phương thức truyền tải HTTP, các thông tin này có thể được cung cấp theo từng yêu cầu dưới dạng tiêu đề, vì vậy mỗi yêu cầu mang thông tin xác thực riêng của nó.

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 theo ID của nó thay vì tra cứu dựa trên lược đồ ở trên và được ưu tiên hơn KBC_WORKSPACE_SCHEMA khi cả hai được đặt. Đây là tùy chọn mà người gọi Ứng dụng dữ liệu / kai-agent cung cấp, dưới dạng tiêu đề X-Workspace-Id, để Kai nhúng trong ứng dụng đó chỉ truy vấn qua không gian làm việc riêng của nó.

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

KBC_STORAGE_API_URL (Khu vực Keboola)

URL API khu vực Keboola của bạn 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 của mình bằng cách nhìn vào URL trong trình duyệt khi đăng nhập vào dự án Keboola của bạn:

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 chức năng của nó trong 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 sản xuất.

• Nếu không được cung cấp, máy chủ sẽ sử dụng nhánh sản xuất theo mặc định.
• Đối với công việc phát triển, hãy đặt KBC_BRANCH_ID thành ID số của nhánh của bạn (ví dụ: 123456). Bạn có thể tìm thấy ID nhánh phát triển trong URL khi điều hướng đến nhánh phát triển trong giao diện người dùng, ví dụ: https://connection.us-east4.gcp.keboola.com/admin/projects/PROJECT_ID/branch/BRANCH_ID/dashboard.
• Trên các kênh 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ó:

• Python 3.10+ đã được cài đặt
• Quyền truy cập vào một dự án Keboola với quyền quản trị
• MCP client ưa thích của bạn (Claude, Cursor, v.v.)

Lưu ý: Đảm bảo bạn đã cài đặt uv. MCP client sẽ sử dụng nó để 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

Để biết thêm các tùy chọn cài đặt, hãy xem tài liệu uv chính thức.

Chạy Keboola MCP Server

Có bốn cách để sử dụng Keboola MCP Server, tùy thuộc vào nhu cầu của bạn:

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

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

1. Đăng nhập một lần trong terminal để lưu phiên (client 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 MCP client (Claude/Cursor) của bạn với các cài đặt bên dưới — chỉ cần KBC_STORAGE_API_URL.
3. Client sẽ tự động khởi chạy máy chủ MCP khi cần.

Cấu hình Claude Desktop

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

{
  "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. Đi tới Settings → MCP
2. Nhấp vào "+ Add new global MCP Server"
3. Cấu hình với các cài đặt 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 ý: Sử dụng tên ngắn, mô tả cho các máy chủ MCP. Vì tên công cụ đầy đủ bao gồm tên máy chủ và phải dưới ~60 ký tự, tên dài hơn có thể bị lọc trong Cursor và sẽ không được 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 sử dụng cấu hình này:

{
  "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 các nhà phát triển làm việc trên mã 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 để sử 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 tra)

Bạn có thể chạy máy chủ thủ công trong terminal để kiểm tra 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 để gỡ lỗi hoặc kiểm tra. Đối với sử dụng thông thường với Claude hoặc Cursor, bạn không cần chạy máy chủ thủ công.

Lưu ý: Máy chủ sẽ sử dụng kênh truyền tải Streamable HTTP và lắng nghe trên localhost:8000 cho các kết nối đến tại /mcp. Bạn có thể sử dụng các tham số --port và --host để làm cho nó lắng nghe ở nơi khác.

Tùy chọn D: Sử dụng Docker

Một container không thể mở trình duyệt, vì vậy hãy xác thực bằng token (xem Xác thực không cần trình duyệt): đặt KBC_STORAGE_TOKEN thành token truy cập/token truy cập cá nhân Keboola và KBC_PROJECT_ID thành dự án mục tiêu. (Qua HTTP, bạn có thể thay vào đó truyền các tiêu đề X-StorageAPI-Token / X-KBC-ProjectId theo từng yêu cầu và bỏ qua các tham số 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ẽ sử dụng kênh truyền tải Streamable HTTP và lắng nghe trên localhost:8000 cho các kết nối đến tại /mcp. Bạn có thể thay đổi -p để ánh xạ cổng của container đến nơi khác.

Tôi Có Cần Tự Khởi Động Máy Chủ Không?

Kịch bản	Cần Chạy Thủ Công?	Sử Dụng Thiết Lập Này
Sử dụng Claude/Cursor	Không	Cấu hình MCP trong cài đặt ứng dụng
Phát triển MCP cục bộ	Không (Claude khởi động nó)	Trỏ cấu hình đến đường dẫn python
Kiểm tra CLI thủ công	Có	Sử dụng terminal để chạy
Sử dụng Docker	Có	Chạy container docker

Sử dụng MCP Server

Khi MCP client (Claude/Cursor) của bạn đã được cấu hình và chạy, bạn có thể bắt đầu truy vấn dữ liệu Keboola của mình:

Xác Minh Thiết Lập Của Bạn

Bạn có thể bắt đầu với 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 Gì 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 một truy vấn để tìm 10 khách hàng hàng đầu theo doanh thu"

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

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

Đường ống Dữ liệu:

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

Tương thích

Hỗ trợ MCP Client

MCP Client	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
MCP Client Tùy chỉnh	✅ Được hỗ trợ	Streamable HTTP hoặc stdio

Các Công cụ Được Hỗ trợ

Lưu ý: Các agent AI của bạn sẽ tự động điều chỉnh theo các công cụ mới.

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

Xử lý 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 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ể sử dụng uv run tox để chạy các bài kiểm tra và kiểm tra kiểu mã.

Thiết lập khuyến nghị:

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

Với thiết lập khuyến nghị, các gói cho việc kiểm tra 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 các bài kiểm tra trong quá trình phát triển.

Kiểm tra tích hợp

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

• INTEGTEST_POOL_STORAGE_API_URL
• INTEGTEST_STORAGE_TOKENS
• INTEGTEST_STORAGE_TOKEN_STORAGE_BRANCHES

Để có được các giá trị này, bạn cần các dự án Keboola chuyên dụng cho các bài kiểm tra tích hợp. Mỗi phiên kiểm tra tạo không gian làm việc chỉ đọc riêng của nó, 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ụ thuộc. Cũng cân nhắc cập nhật khóa với 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 bạn thực hiện thay đổi đối với bất kỳ mô tả công cụ nào (docstrings 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 cắt bản phát hành cho mỗi PR được hợp nhất. Công việc hạ cánh trên nhánh chính (main) liên tục, và chúng tôi phát hành định kỳ sau khi các thay đổi được kiểm tra lại cùng nhau — điều này tránh làm hỏng các thiết lập hoạt động của người dùng.

Một bản phát hành được thực hiện bằng cách đẩy một hoặc hai git tag:

• 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ột trong hai tag kích hoạt CI release.yml, CI này xây dựng và xuất bản hình ảnh Docker. KaiBench chỉ chạy trên các tag vX.Y.Z sản xuất (không phải agent-vX.Y.Z, và không phải các bản phát hành trước -dev.). Sử dụng kỹ năng release-notes — nó chuẩn bị ghi chú phát hành và PR nháp và hướng dẫn gắn tag 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 cá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 tích cực theo dõi các issue và sẽ phản hồi nhanh 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 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 cho MCP Server

Kết nối

• LinkedIn
• Twitter
• Changelog