Keboola MCP Server

chính thức

Xây dựng các quy trình dữ liệu, tích hợp và phân tích mạnh mẽ trên một nền tảng trực quan duy nhất.

Tài liệu

Máy chủ Keboola MCP

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 với Keboola. Truy xuất dữ liệu, các phép biến đổi, truy vấn SQL và kích hoạt công việc—không cần mã kết dính. Cung cấp dữ liệu phù hợp cho tác nhân khi nào và ở đâu họ cần.

Tổng quan

Máy chủ Keboola MCP 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ữ, biế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.v.

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 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 trích xuất, ghi, ứng dụng dữ liệu và biến đổi
SQL: Tạo các biến đổi SQL bằng ngôn ngữ tự nhiên
Công việc: Chạy các thành phần và biế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 pipeline 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ý Ứng dụng dữ liệu Keboola Streamlit 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 bê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ủ Keboola MCP là thông qua Máy chủ MCP từ xa của chúng tôi. 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ộ.

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 người dùng 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 có thể truyền phát từ xa và xác thực OAuth.

Cách kết nối

Lấy URL máy chủ từ xa của bạn: Điều hướng đến Cài đặt dự án Keboola → tab MCP Server
Sao chép URL máy chủ: Nó sẽ trông giống như https://mcp.<YOUR_REGION>.keboola.com/mcp
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
Xác thực: Bạn sẽ được nhắc xác thực bằng tài khoản Keboola của mình và chọn dự án

Các 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 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 máy 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 của mình. Bạn có thể cài đặt tích hợp Máy chủ Keboola MCP bằng một lệnh đơn giản.

Cài đặt:

Chạy lệnh sau trong terminal 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

Các 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 Máy chủ Keboola MCP trong Claude Code bằng cách nhập /mcp vào cuộc trò chuyện của mình 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ủ Keboola MCP lần đầu tiên trong Claude Code, một cửa sổ trình duyệt sẽ mở ra nhắc bạn:

Đăng nhập bằng tài khoản Keboola của bạn
Chọn dự án bạn muốn kết nối
Ủ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.

Để biết 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 của chúng tôi.

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 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 đã 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ẽ sử dụng nhánh sản xuất làm mặc định. Điều 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 (HTTP có thể truyền phát), bạn có thể kiểm soát những công cụ nào khả dụng cho máy khách bằng các 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 bộ lọc

Các bộ lọc áp dụng theo thứ tự: được phép → giao với 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. Những 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ác công cụ chỉ đọc, hãy xem tệp TOOLS.md 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 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ẽ sao chép kho lưu trữ, đặt thông tin xác thực Keboola qua biến môi trường hoặc tiêu đề tùy thuộc vào phương thức truyền tải máy chủ, cài đặt các phụ thuộc và khởi động máy chủ. 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 phương thức 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 truyền phát 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 - Bí danh cho streamable-http, được giữ lại để tương thích ngược.

Đối với giao tiếp máy khách–máy chủ, thông tin xác thực Keboola phải được cung cấp để cho phép làm việc với dự án của bạn trong Khu vực Keboola của bạn. Các thông tin sau là bắt buộc: KBC_STORAGE_TOKEN, KBC_STORAGE_API_URL, KBC_WORKSPACE_SCHEMA và tùy chọn KBC_BRANCH_ID. Bạn có thể cung cấp chúng theo hai cách:

Đối với mục đích sử dụng cá nhân (chủ yếu với phương thức truyền tải stdio): đặt các biến môi trường trước khi khởi động máy chủ. Tất cả các yêu cầu sẽ sử dụng lại các thông tin xác thực được xác định trước này.
Đối với mục đích sử dụng nhiều người dùng: bao gồm các biến trong tiêu đề yêu cầu để mỗi yêu cầu sử dụng thông tin xác thực được cung cấp cùng với nó.

KBC_STORAGE_TOKEN

Đây là mã thông báo xác thực của bạn cho Keboola:

Để biết hướng dẫn về cách tạo và quản lý mã thông báo API lưu trữ, hãy tham khảo tài liệu chính thức của Keboola.

Lưu ý: Nếu bạn muốn máy chủ MCP có quyền truy cập hạn chế, hãy sử dụng mã thông báo lưu trữ tùy chỉnh, nếu bạn muốn MCP truy cập mọi thứ trong dự án của mình, hãy sử dụng mã thông báo chính.

KBC_WORKSPACE_SCHEMA

Điều này xác định không gian làm việc của bạn trong Keboola và được sử dụng cho các truy vấn SQL. Tuy nhiên, điều này chỉ bắt buộc nếu bạn đang sử dụng mã thông báo lưu trữ tùy chỉnh thay vì Mã thông báo chính:

Nếu sử dụng Mã thông báo chính: Không gian làm việc được tạo tự động ở hậu trường
Nếu sử dụng mã thông báo lưu trữ tùy chỉnh: Làm theo hướng dẫn Keboola này để lấy KBC_WORKSPACE_SCHEMA của bạn

Lưu ý: Khi tạo không gian làm việc thủ công, hãy chọn tùy chọn Cấp quyền truy cập chỉ đọc vào tất cả dữ liệu Dự án

Lưu ý: KBC_WORKSPACE_SCHEMA được gọi là Tên tập dữ liệu trong các không gian làm việc BigQuery, bạn chỉ cần nhấp vào kết nối và sao chép Tên tập dữ liệu

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 xem 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)

Để hoạt động 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 đã chỉ định, đảm bảo tất cả các thay đổi vẫn được cách ly 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ử 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 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.10+
Quyền truy cập vào dự án Keboola với quyền quản trị viên
Máy khách MCP ưa thích của bạn (Claude, Cursor, v.v.)

Lưu ý: Đảm bảo bạn đã cài đặt uv. Máy khách MCP sẽ sử dụng nó để tự động tải xuống và chạy Máy chủ Keboola MCP. 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 chính thức của uv.

Chạy Máy chủ Keboola MCP

Có bốn cách để sử dụng Máy chủ Keboola MCP, 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. Bạn không cần chạy bất kỳ lệnh nào trong terminal của mình.

Cấu hình máy khách MCP của bạn (Claude/Cursor) với các cài đặt thích hợp
Máy khách sẽ tự động khởi chạy máy chủ MCP khi cần

Cấu hình Claude Desktop

Đi tới Claude (góc trên cùng bên trái màn hình của bạn) -> Cài đặt → Nhà phát triển → Chỉnh sửa cấu hình (nếu bạn không thấy claude_desktop_config.json, hãy tạo nó)
Thêm cấu hình sau:
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_STORAGE_TOKEN": "your_keboola_storage_token",
        "KBC_WORKSPACE_SCHEMA": "your_workspace_schema",
        "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

Đi tới Cài đặt → MCP
Nhấp vào "+ Thêm máy chủ MCP toàn cục mới"
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_STORAGE_TOKEN": "your_keboola_storage_token",
        "KBC_WORKSPACE_SCHEMA": "your_workspace_schema",
        "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ự, các tên dài hơn có thể bị lọc ra trong Cursor và sẽ không được hiển thị cho Tác nhân.

Cấu hình Cursor cho Windows WSL

Khi chạy máy chủ MCP từ Hệ thống con Windows cho 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_STORAGE_TOKEN=your_keboola_storage_token &&",
          "export KBC_WORKSPACE_SCHEMA=your_workspace_schema &&",
          "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ực tiếp trên mã máy chủ MCP:

Sao chép kho lưu trữ và thiết lập môi trường cục bộ
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_STORAGE_TOKEN": "your_keboola_storage_token",
        "KBC_WORKSPACE_SCHEMA": "your_workspace_schema",
        "KBC_BRANCH_ID": "your_branch_id_optional"
      }
    }
  }
}

Tùy chọn C: Chế độ CLI Thủ công (Chỉ dành cho Kiểm thử)

Bạn có thể chạy máy chủ thủ công trong terminal để kiểm thử hoặc gỡ lỗi:

# Set environment variables
export KBC_STORAGE_API_URL=https://connection.YOUR_REGION.keboola.com
export KBC_STORAGE_TOKEN=your_keboola_storage_token
export KBC_WORKSPACE_SCHEMA=your_workspace_schema
export KBC_BRANCH_ID=your_branch_id_optional

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ử. Đối với việc sử dụng thông thường với Claude hoặc Cursor, bạn không cần phải chạy máy chủ thủ công.

Lưu ý: Máy chủ sẽ sử dụng truyền tải HTTP có thể truyền phát 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 để khiến nó lắng nghe ở nơi khác.

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

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_STORAGE_TOKEN" \
  -e KBC_WORKSPACE_SCHEMA="YOUR_WORKSPACE_SCHEMA" \
  -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 truyền tải HTTP có thể truyền phát 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 sang nơi khác.

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

Tình huống	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 thử CLI thủ công	Có	Sử dụng terminal để chạy
Sử dụng Docker	Có	Chạy container docker

Sử dụng Máy chủ MCP

Khi máy khách MCP (Claude/Cursor) của bạn đã được cấu hình và đang 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ứ đang 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 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 trong 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 biến đổi SQL kết hợp 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"

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ợ	HTTP có thể truyền phát
Máy khách MCP tùy chỉnh	✅ Được hỗ trợ	HTTP có thể truyền phát 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 đ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.

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	Xác minh `KBC_STORAGE_TOKEN` hợp lệ
Vấn đề Không gian làm việc	Xác nhận `KBC_WORKSPACE_SCHEMA` chính xác
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 kiểm thử 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 để 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ộ, 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 kiểm thử tích hợp. Mỗi phiên kiểm thử tạo 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ụ 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 đã hợp nhất. Công việc được đưa lê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 thử lại cùng nhau — điều này tránh làm hỏng các thiết lập đang 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 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 Tác nhân Trong Nền tảng (chỉ khi tác nhân cũng đang được phát hành)

Một trong hai thẻ 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 thẻ vX.Y.Z sản xuất (không phải agent-vX.Y.Z, và không phải 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, đồng thời hướng dẫn gắn thẻ 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 Máy chủ MCP

Keboola MCP Server

Tài liệu

Máy chủ Keboola MCP

Tổng quan

Tính năng

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

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

Cách kết nối

Các máy khách được hỗ trợ

Thiết lập Claude Code

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

Ủy quyền công cụ và Kiểm soát truy cập

Tiêu đề ủy quyền

Hành vi bộ lọc

Công cụ chỉ đọc

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

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

KBC_STORAGE_TOKEN

KBC_WORKSPACE_SCHEMA

KBC_STORAGE_API_URL (Khu vực Keboola)

KBC_BRANCH_ID (Tùy chọn)

Cài đặt

Chạy Máy chủ Keboola MCP

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

Cấu hình Claude Desktop

Cấu hình Cursor

Cấu hình Cursor cho Windows WSL

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

Tùy chọn C: Chế độ CLI Thủ công (Chỉ dành cho Kiểm thử)

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

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

Sử dụng Máy chủ MCP

Xác minh Thiết lập của bạn

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

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

Hỗ trợ Máy khách MCP

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

Khắc phục sự cố

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

Phát triển

Cài đặt

Kiểm thử tích hợp

Cập nhật uv.lock

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

Phát hành

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

Tài nguyên

Kết nối

Cập nhật `uv.lock`