Cài đặtInstall

Cài trong 5 phút —
AI tự làm phần khó.Install in 5 minutes —
the AI does the hard part.

3 cách từ dễ đến thủ công. Với hầu hết mọi người: dùng Cách 1 — dán một câu cho AI của bạn, nó tự cài mọi thứ trên cả 3 nền tảng (Claude Code, Codex, Antigravity).

Trước khi cài

Máy cần có gì

Thành phần	Ghi chú
Windows 10/11	Power BI Desktop chỉ chạy trên Windows
Power BI Desktop	Bản cài thường hoặc Microsoft Store đều được
Python 3.11+	Kiểm tra: `python --version`. Chưa có → tải tại đây (tick "Add to PATH")
ADOMD.NET	Có sẵn nếu máy đã cài SSMS (bản 18–22). Chưa có → cài Analysis Services client libraries. Trình cài tự dò mọi vị trí.
1 AI agent	Claude Code · Codex CLI · Google Antigravity (một trong ba, hoặc cả ba)

KHUYẾN NGHỊ

Cách 1 — Đưa cho chính AI cài

Dành cho: tất cả mọi người · thời gian: ~5 phút · không cần biết dòng lệnh

Mở AI của bạn, dán nguyên câu này. AI sẽ tải mã nguồn, đọc trình cài trước khi chạy, dựng môi trường, đăng ký vào cả 3 nền tảng và tự học 4 skill + 8 lệnh:

dán vào AI

Clone https://github.com/ducnguyen221/powerbi-agent
vào ~/.mcp/powerbi-mcp rồi chạy install.ps1 trong đó
(đọc script trước khi chạy), sau đó restart MCP host.

Xong thì khởi động lại AI và gõ /powerbi-setup — xem tiếp Hướng dẫnGuide.

Cách 2 — Tự chạy lệnh (git + installer)

Dành cho: người quen dòng lệnh, muốn kiểm soát từng bước

PowerShell

# 1. Lấy mã nguồn về đúng chỗ khuyến nghị
git clone https://github.com/ducnguyen221/powerbi-agent "$env:USERPROFILE\.mcp\powerbi-mcp"
cd "$env:USERPROFILE\.mcp\powerbi-mcp"
# 2. Cài in-place: venv + dò ADOMD/TOM + đăng ký 3 host + skills + lệnh
powershell -ExecutionPolicy Bypass -File .\install.ps1
# 3. (khuyến nghị) cài kèm modeling chính chủ Microsoft
claude mcp add powerbi-modeling -s user -- npx -y "@microsoft/powerbi-modeling-mcp@latest" --start

Trình cài idempotent (chạy lại an toàn), backup config trước khi sửa, không đụng file bí mật. Tham số: -Hosts claude,codex,antigravity chọn nền tảng · -SkipVenv chỉ cập nhật đăng ký. Bản hướng dẫn chi tiết từng bước + ảnh: INSTALL.html.

Cách 3 — Chỉ cài skills (dạng plugin, không cần Python)

Dành cho: người chỉ cần quy trình & kiến thức (chưa cần AI thao tác trực tiếp lên Power BI)

Claude Code / Codex

claude plugin marketplace add ducnguyen221/powerbi-agent
claude plugin install powerbi-agent@powerbi-agent

Muốn đủ 16 công cụ (truy vấn, dựng báo cáo…) → quay lại Cách 1/2.

Sau khi cài

Kiểm tra 30 giây

Khởi động lại AI

Đóng mở lại Claude Code / Codex / Antigravity để nhận công cụ mới.

Kiểm tra kết nối

Claude Code: chạy claude mcp list — phải thấy powerbi-mcp-bridge ✔ Connected.

Thử lệnh đầu tiên

Mở 1 file .pbix bất kỳ trong Power BI Desktop rồi hỏi AI: "Liệt kê các báo cáo Power BI đang mở và cho xem danh sách bảng của model." AI trả về danh sách bảng = cài thành công 🎉

Thiết lập bộ nhớ tri thức

Gõ /powerbi-setup — chỉ định thư mục lưu tri thức dự án (1 lần). Chi tiết: Hướng dẫnGuide.

Khi có vấn đề

Sự cố thường gặp

Triệu chứng	Cách xử lý
Công cụ không xuất hiện	Khởi động lại AI; kiểm tra `claude mcp list`
Báo thiếu ADOMD.NET	Cài SSMS hoặc Analysis Services client libraries; hoặc đặt biến môi trường `ADOMD_LIB_DIR` trỏ tới thư mục chứa DLL
Không tìm thấy báo cáo đang mở	Power BI Desktop phải ĐANG mở 1 file; chờ vài giây cho engine khởi động
Truy vấn bị chặn "aggregate-only"	Là chủ đích (bảo vệ dữ liệu chi tiết). AI sẽ tự viết lại dạng tổng hợp; thực sự cần dữ liệu thô → đặt `POWERBI_AGGREGATE_ONLY=0`
Trang báo cáo AI tạo không thấy	File .pbip phải ĐÓNG khi AI ghi; nếu đang mở → Đóng KHÔNG lưu rồi mở lại

Không tự xử được? Mở GitHub Issues — kèm thông báo lỗi và bước tái hiện.

Cài trong 5 phút —AI tự làm phần khó.Install in 5 minutes —the AI does the hard part.