Chuyển tới nội dung chính
Trang được dịch

Trang này được dịch từ tiếng Anh với sự hỗ trợ của AI. Nếu hai bản có chỗ khác nhau, hãy lấy phiên bản tiếng Anh làm chuẩn.

Cài đặt

Trang này cung cấp hướng dẫn cài đặt StackQL trên nhiều nền tảng khác nhau.

macOS​

StackQL khả dụng trên macOS qua Homebrew và trình cài đặt pkg; cả kiến trúc ARM (M1/Apple Silicon) và AMD đều được hỗ trợ bằng một trình cài đặt đa kiến trúc duy nhất.

Để cài đặt qua Homebrew, chạy lệnh sau trong terminal của bạn:

brew install stackql

Sử dụng với ứng dụng khách MCP​

Máy chủ MCP StackQL chạy cục bộ qua stdio, nên thông tin xác thực provider luôn nằm trên máy của bạn, dù bạn dùng ứng dụng khách nào. Chọn ứng dụng khách của bạn bên dưới: mỗi tab trình bày trước cách cài đặt qua thư mục hoặc bằng một cú nhấp, sau đó là cấu hình thủ công làm fallback. Để biết mọi kênh phân phối, bao gồm npx, Python, Docker và CI, hãy xem Cài đặt máy chủ MCP.

Claude Desktop​

Cách được khuyên dùng để cài đặt máy chủ MCP StackQL vào Claude Desktop là từ Anthropic Connector Directory (Settings -> Connectors -> Add -> Browse Connectors, tìm StackQL) - Claude Desktop tự động chọn đúng tệp nhị phân được ký cho nền tảng của bạn. Ngoài ra, các MCP Bundle (.mcpb) dựng sẵn được đính kèm vào mọi bản phát hành StackQL để cài đặt từ tệp đã tải xuống - dù theo cách nào, bạn cũng không cần cài đặt StackQL riêng. Bundle khả dụng cho macOS, Windows và Linux.

Bản tải xuống MCPB cho Linux và Windows mặc định là amd64 (x64). Dùng danh sách thả xuống để chọn amd64 hoặc arm64.


thông tin

Máy chủ MCP StackQL cũng được liệt kê trên Official MCP Registry với tên io.github.stackql/stackql-mcp.

mẹo

Bundle là một trong nhiều cách để chạy máy chủ MCP StackQL. Xem Sử dụng StackQL với Claude Desktop để biết hướng dẫn đầy đủ cho Claude Desktop, hoặc Cài đặt máy chủ MCP để biết các tùy chọn npx, Docker, Python, CI và thủ công.

Cài đặt máy chủ MCP​

Máy chủ MCP StackQL cho phép tác nhân AI truy vấn và cấp phát tài nguyên đám mây bằng StackQL. Máy chủ được phân phối qua nhiều kênh - tất cả đều chạy cùng một máy chủ, vì vậy hãy chọn kênh phù hợp với ứng dụng khách và yêu cầu tin cậy của bạn. Các tùy chọn bên dưới được sắp xếp gần đúng theo mức độ tin cậy và mức độ dễ dùng.

Marketplace và thư mục​

Máy chủ được phát hành lên Official MCP Registry với tên io.github.stackql/stackql-mcp; các registry gói bên dưới chứa các artifact để phân phối, và các thư mục ở hạ nguồn lấy mục từ đó.

RegistryLoạiPhát hành quaMụcGhi chú
Official MCP RegistryRegistry siêu dữ liệu chuẩnCLI mcp-publisher + server.jsonmodelcontextprotocol.io/search
modelcontextprotocol.io/direct
công bố cả 8 gói (mcpb x5, oci, npm, pypi)
npmRegistry góinpm publish@stackql/mcp-servertrình khởi chạy npx
PyPIRegistry góitwine uploadstackql-mcp-servertrình khởi chạy uvx / pip
Docker HubRegistry containerdocker buildx --pushstackql/stackql-mcpđa kiến trúc amd64 + arm64
GitHub Actions MarketplaceMarketplace CI (action setup-stackql-mcp)Kho lưu trữ công khai + bản phát hành + mục marketplacesetup-stackql-mcp-serverNhà phát hành đã xác minh; stackql/setup-stackql-mcp

Bundle .mcpb dựng sẵn​

Khi nào nên dùng: Claude Desktop không có quyền truy cập Connector Directory, hoặc khi bạn muốn ghim một phiên bản cụ thể hoặc tự xác minh checksum trước khi cài đặt. Với hầu hết người dùng Claude Desktop, Anthropic Connector Directory là cách cài đặt được khuyên dùng.

Mỗi bản phát hành StackQL đều đính kèm một MCP Bundle dựng sẵn cho từng nền tảng:

https://releases.stackql.io/stackql/latest/stackql-mcp-<platform>.mcpb

trong đó <platform> là một trong các giá trị darwin-universal, windows-x64 (AMD64), windows-arm64, linux-x64 hoặc linux-arm64. Các nút tải xuống cho từng nền tảng nằm trong tab Claude Desktop ở phần Sử dụng với ứng dụng khách MCP. Mỗi bundle có một checksum .sha256 tương ứng trên trang phát hành. Xác minh checksum, sau đó cài đặt qua Settings -> Extensions trong Claude Desktop:

shasum -a 256 -c stackql-mcp-darwin-universal.mcpb.sha256

Xem Sử dụng StackQL với Claude Desktop để biết hướng dẫn từng bước đầy đủ.

Cấu hình claude_desktop_config.json thủ công​

Khi nào nên dùng: bạn đã có tệp nhị phân stackql trong PATH và dùng Claude Desktop hoặc bất kỳ ứng dụng khách MCP stdio nào khác.

{
"mcpServers": {
"stackql": {
"command": "stackql",
"args": [
"mcp",
"--mcp.server.type=stdio",
"--approot", "/Users/you/.stackql",
"--mcp.config", "{\"server\": {\"audit\": {\"disabled\": true}}}"
]
}
}
}

Cả ba đối số đều không thể thiếu:

  • --mcp.server.type=stdio chọn phương thức truyền tải stdio mà các ứng dụng khách nhúng trong trình soạn thảo sử dụng.
  • --approot trỏ cache provider đến một thư mục có thể ghi. Ứng dụng khách MCP có thể khởi chạy máy chủ với thư mục làm việc là /, vốn không thể ghi.
  • --mcp.config '{"server": {"audit": {"disabled": true}}}' tắt nhật ký kiểm tra; nếu không tắt, nhật ký này mặc định dùng thư mục làm việc (có thể không ghi được) làm thư mục của nó.

Thêm thông tin xác thực provider bằng khối "env" và điều chỉnh hợp đồng an toàn bằng "mode" - xem Chế độ máy chủ.

npx (không cần cài đặt)​

Khi nào nên dùng: mọi môi trường Node, khi bạn không muốn cài đặt StackQL toàn cục.

{ "mcpServers": { "stackql": { "command": "npx", "args": ["-y", "@stackql/mcp-server"] } } }

Trình khởi chạy @stackql/mcp-server tải xuống tệp nhị phân stackql được ký trong lần chạy đầu tiên, xác minh SHA-256 của tệp và lưu tệp vào cache cho các lần chạy sau.

uvx / pip (Python)​

Khi nào nên dùng: môi trường Python - cùng trình khởi chạy đó được đóng gói cho Python, dùng chung cache tệp nhị phân mà trình khởi chạy npx tạo ra.

{ "mcpServers": { "stackql": { "command": "uvx", "args": ["stackql-mcp-server"] } } }

Hoặc cài đặt vào môi trường hiện tại bằng pip install stackql-mcp-server (Python 3.9+). Gói này có tên stackql-mcp-server trên PyPI.

Docker​

Khi nào nên dùng: runtime chạy trong container hoặc được cô lập theo cách khác. Image hỗ trợ đa kiến trúc (amd64 và arm64).

docker run -i --rm stackql/stackql-mcp

Dưới dạng cấu hình ứng dụng khách:

{ "mcpServers": { "stackql": { "command": "docker", "args": ["run", "-i", "--rm", "stackql/stackql-mcp"] } } }

Image này có tên stackql/stackql-mcp trên Docker Hub.

CI và quy trình làm việc dựa trên tác nhân (GitHub Actions)​

Khi nào nên dùng: chạy máy chủ bên trong một job GitHub Actions để tác nhân có thể truy vấn - và, nếu bạn cho phép, thao tác trên - môi trường đám mây của bạn như một phần của CI.

stackql/setup-stackql-mcp@v1 cài đặt tệp nhị phân và ghi một cấu hình MCP (mặc định ở chế độ read_only). Truyền cấu hình đó cho anthropics/claude-code-action qua claude_args:

- id: stackql
uses: stackql/setup-stackql-mcp@v1
with:
auth: '{"github":{"type":"null_auth"}}'

- uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
prompt: |
Using stackql, list the public repositories in the stackql org and
summarise them as a markdown table.
claude_args: |
--mcp-config ${{ steps.stackql.outputs.mcp-config-file }}
--allowedTools 'mcp__stackql__*'

Xem README của action để biết thêm các công thức dựa trên tác nhân (kiểm tra đám mây, ước tính chi phí, v.v.).

MCP nhúng​

Khi nào nên dùng: bạn đang xây dựng một ứng dụng dựa trên tác nhân và muốn đưa máy chủ MCP vào tệp nhị phân của mình theo kiểu vendoring - không cần npx, không cần cài đặt riêng, không có phần phụ thuộc runtime.

Các thư viện gốc khởi chạy tệp nhị phân stackql được ký qua stdio, phía sau ứng dụng khách SDK MCP chính thức của từng ngôn ngữ, nhờ đó ứng dụng của bạn có cùng một giao diện SQL được quản trị đến mọi provider trong registry. Mỗi thư viện mặc định dùng read_only - việc nâng lên chế độ có quyền ghi luôn phải được chỉ định rõ ràng - và có thể tải xuống rồi xác minh tệp nhị phân trong lần chạy đầu tiên, hoặc đưa nó vào bản dựng của bạn theo kiểu vendoring để có một tệp thực thi độc lập duy nhất. API đầy đủ cho từng ngôn ngữ có trong tài liệu tham khảo MCP nhúng.

Crate stackql-mcp khởi chạy tệp nhị phân phía sau một ứng dụng khách rmcp. Tính năng mặc định sidecar tải xuống và xác minh tệp nhị phân trong lần chạy đầu tiên; tính năng vendored nhúng tệp nhị phân bằng include_bytes! để có một tệp nhị phân độc lập duy nhất. MSRV Rust 1.88.

# Cargo.toml
stackql-mcp = "0.1"
use stackql_mcp::{Mode, StackqlMcp};

let server = StackqlMcp::builder()
.mode(Mode::ReadOnly)
.start()
.await?;
let tools = server.list_all_tools().await?;

Tài liệu tham khảo đầy đủ: MCP nhúng: Rust.

Mô hình tin cậy​

Các thuộc tính bảo mật sau áp dụng như nhau cho mọi kênh:

  • Tệp nhị phân stackql nhúng được ký bằng Authenticode (Windows) và được Apple công chứng (macOS).
  • Mỗi bundle .mcpb đều đi kèm một checksum SHA-256 được đăng trên trang phát hành.
  • Trình khởi chạy npx và uvx xác minh SHA-256 của tệp nhị phân đã tải xuống trước lần sử dụng đầu tiên.
  • Mục trên MCP Registry xác nhận hash của từng nền tảng.

Sử dụng GitHub Actions​

Bạn có thể dùng GitHub Actions StackQL trong các workflow GitHub Actions của mình. Hiện có các action sau:

stackql-deploy​

Triển khai hoặc kiểm thử các stack hạ tầng bằng StackQL trực tiếp từ các workflow GitHub của bạn. Action này hỗ trợ các workflow hạ tầng dưới dạng mã (IaC) bằng cú pháp giống SQL, giúp bạn định nghĩa, triển khai và quản lý tài nguyên đám mây trên nhiều provider trong một workflow duy nhất.


Ví dụ sử dụng

...
jobs:
stackql-actions-test:
name: StackQL Actions Test
runs-on: ubuntu-latest
env:
GOOGLE_CREDENTIALS: ${{ secrets.GOOGLE_CREDENTIALS }} # add additional cloud provider creds here as needed

steps:
- name: Checkout
uses: actions/checkout@v6

- name: Deploy a Stack
uses: stackql/stackql-deploy-action@v2
with:
command: 'build'
stack_dir: 'examples/k8s-the-hard-way'
stack_env: 'dev'
env_vars: |
GOOGLE_PROJECT=stackql-k8s-the-hard-way-demo
GOOGLE_REGION=australia-southeast1

Các thư viện khác​

StackQL cung cấp nhiều cách tích hợp để dùng trong các ngôn ngữ lập trình và môi trường khác nhau. Các thư viện này mở rộng các tính năng của StackQL, giúp bạn dễ dàng đưa việc truy vấn và quản lý tài nguyên đám mây vào các ứng dụng và workflow hiện có.

Gói Python pystackql​

Wrapper Python để dùng StackQL trong các chương trình Python của bạn. Gói pystackql có trên PyPI, tài liệu cho gói pystackql có trên Read the Docs. Để cài đặt gói pystackql, chạy lệnh sau:

pip install pystackql

Ví dụ sau cho thấy gói pystackql được dùng cùng pandas để chạy truy vấn StackQL và trả kết quả về một pandas.DataFrame:

from pystackql import StackQL
import pandas as pd
region = "ap-southeast-2"
stackql = StackQL()

query = """
SELECT instance_type, COUNT(*) as num_instances
FROM aws.ec2.instances
WHERE region = '%s'
GROUP BY instance_type
""" % (region)

res = stackql.execute(query)
df = pd.read_json(res)
print(df)