MCP Inspector: kiểm thử MCP server — hướng dẫn cài đặt và dùng

Tóm tắt nhanh
MCP Inspector là bộ công cụ kiểm tra Model Context Protocol server qua Web, CLI hoặc giao diện terminal. Bạn có thể dùng nó để kiểm tra server thủ công, chạy smoke test và đưa vào CI; việc cài đặt khá đơn giản nếu máy có Node đúng phiên bản.
MCP Inspector là công cụ dành cho việc kiểm tra và debug các MCP server. Repo cung cấp một gói duy nhất nhưng có nhiều cách dùng: giao diện Web, CLI để chạy bằng lệnh, TUI trong terminal và mcpdo để giữ một kết nối rồi chạy nhiều lệnh.
Công cụ này phù hợp với lập trình viên xây MCP server, đội kỹ thuật cần kiểm tra server trước khi tích hợp, hoặc người muốn xem nhanh server có kết nối được, liệt kê được công cụ và phản hồi đúng không. Điểm đáng giá nhất là cùng một gói có thể phục vụ cả kiểm tra thủ công lẫn tự động hoá trong shell hoặc CI.
Repo hiện có khoảng 11288 sao và 1570 fork. Mã nguồn chính dùng TypeScript, đang tiếp tục được cập nhật. Đây là dòng v2 của Inspector; dòng v1 vẫn tồn tại riêng cho các trường hợp cần tương thích cũ.
modelcontextprotocol/inspector
Công cụ Web, CLI và TUI giúp kiểm tra, gọi thử, debug và tự động hoá việc kiểm thử MCP server.
I.MCP Inspector làm được gì
Mở giao diện Web để kiểm tra MCP server: Web UI phù hợp khi bạn muốn quan sát bằng chuột, xem thông tin kết nối và thao tác trực tiếp trong trình duyệt. Đây thường là cách dễ bắt đầu nhất nếu bạn chưa quen CLI.
Chạy CLI cho tự động hoá: CLI có thể được gọi từ shell, script hoặc quy trình CI. Cách này phù hợp khi bạn muốn kiểm tra MCP server lặp lại và nhận kết quả có thể xử lý tiếp.
Dùng TUI ngay trong terminal: TUI cung cấp giao diện tương tác trong cửa sổ dòng lệnh. Bạn có thể dùng khi đang làm việc qua SSH, không muốn mở trình duyệt hoặc thích thao tác bằng bàn phím.
Kết nối và chạy nhiều lệnh bằng mcpdo: mcpdo là CLI thử nghiệm. Nó kết nối một lần, sau đó cho phép chạy nhiều lệnh trên kết nối có tên thông qua một daemon cục bộ. Cách này hữu ích cho phiên làm việc dài hoặc tác vụ cần gọi server nhiều lần.
Kiểm thử theo quy trình rõ ràng: Tài liệu của repo mô tả quy trình kết nối, liệt kê, gọi và kiểm tra kết quả. Với shell hoặc CI, CLI có thể xuất JSON để kết hợp với jq và kiểm tra bằng mã thoát.
Hỗ trợ kiểm tra MCP App: Repo có hướng dẫn cho quy trình xem xét MCP App theo cách CLI trước, sau đó dùng Web một lần khi cần quan sát giao diện.
Quản lý thông tin nhạy cảm: Inspector có thể làm việc với OAuth token, OAuth client secret và giá trị trong
stdio env:. Theo mặc định, công cụ cố gắng lưu chúng trong OS keychain nếu hệ điều hành cung cấp.Có thể chạy bằng container: Repo có Dockerfile và tài liệu riêng cho Docker. Tài liệu này đề cập đến cổng, volume và cách giữ secrets bền vững trong container.
Có thể phục vụ Web qua HTTPS: Repo có tài liệu về biến
INSPECTOR_TLS_KEY_PATH,INSPECTOR_TLS_CERT_PATH, hostname tuỳ chỉnh,ALLOWED_ORIGINSvàNODE_EXTRA_CA_CERTScho server dùng CA riêng.
II.Cần chuẩn bị gì
Bạn cần Node.js đúng engine mà package.json yêu cầu: ^22.23.4 || ^24.22.1 || >=26.12.1. Đây là yêu cầu quan trọng. Nếu Node thấp hơn hoặc không nằm trong các dòng được hỗ trợ, quá trình cài đặt hay chạy build có thể thất bại.
Nếu cài từ mã nguồn, bạn cần npm và một bản sao của repo. README hướng dẫn chạy npm install ở thư mục gốc. Repo không phải npm workspace; mỗi client trong clients/* có package.json và node_modules riêng, còn mã dùng chung nằm trong core/.
Bạn cũng cần có MCP server muốn kiểm tra và cấu hình kết nối tương ứng. README cho biết repo có tài liệu riêng về định dạng cấu hình MCP server, nhưng phần nội dung cấu hình cụ thể không nằm trong tư liệu được cung cấp ở đây.
Nếu dùng OAuth hoặc giá trị bí mật trong stdio env:, cần chú ý nơi Inspector lưu secrets. Máy có OS keychain sẽ dùng keychain nếu có thể. Linux không có libsecret hoặc Secret Service, phiên SSH không có keychain, Termux và container có volume gắn vào có thể dùng ~/.mcp-inspector/secrets.json. Trong trường hợp đó, file có thể không được mã hoá nếu bạn không cung cấp key.
III.Cài đặt từng bước
- Kiểm tra NodeBảo đảm Node nằm trong engine được hỗ trợ
- Lấy mã nguồnClone repo và đi vào thư mục dự án
- Cài dependencyChạy npm install tại thư mục gốc
- Build dự ánChạy npm run build để build Web, CLI, TUI và launcher
- Chọn cách chạyMở Web, CLI, TUI hoặc xem trợ giúp mcpdo
A.Kiểm tra phiên bản Node
Nếu bạn cài từ mã nguồn, trước hết hãy mở PowerShell hoặc terminal tại nơi bạn muốn lưu dự án. README yêu cầu Node thuộc một trong các dòng sau:
^22.23.4 || ^24.22.1 || >=26.12.1Đây là điều kiện phiên bản, không phải lệnh để chạy trực tiếp. Hãy kiểm tra phiên bản Node bằng công cụ quản lý Node hoặc lệnh kiểm tra sẵn có trên máy. Nếu phiên bản không phù hợp, hãy đổi sang bản được hỗ trợ trước khi cài dependency.
B.Clone repo và đi vào thư mục
README không ghi nguyên lệnh clone, nên bạn có thể dùng lệnh phổ thông sau:
git clone https://github.com/modelcontextprotocol/inspector.git
cd inspectorLệnh đầu tiên tải mã nguồn về thư mục inspector. Lệnh thứ hai đưa terminal vào đúng thư mục dự án. Người mới thường chạy npm install ở thư mục cha, khiến dependency được cài sai chỗ; hãy kiểm tra đường dẫn hiện tại trước khi chạy bước tiếp theo.
C.Cài dependency
Tại thư mục gốc của repo, chạy đúng lệnh README cung cấp:
npm install # at the repo root; postinstall cascades into every clientLệnh này cài dependency ở root. Hook postinstall tiếp tục cài cho các client bên trong repo. Vì dự án không phải npm workspace, bạn không nên tự ý gom các client vào một workspace khác hoặc xoá cấu trúc clients/*.
D.Build toàn bộ dự án
Sau khi cài xong, chạy:
npm run build # web → cli → tui → launcherBuild lần lượt Web, CLI, TUI và launcher. Đây là bước cần thiết trước khi dùng các script chạy thông qua launcher, vì các script đó chạy bản launcher đã build.
E.Chạy Web trong quá trình phát triển
Nếu bạn đang sửa mã nguồn Web và muốn cập nhật nhanh, README hướng dẫn chạy Vite trực tiếp:
cd clients/web && npm run devCách này dành cho vòng lặp phát triển Web và có HMR. Bạn cần chạy từ repo đã được cài dependency. Nếu chỉ muốn dùng bản launcher, hãy build trước rồi dùng script tương ứng.
F.Chạy các chế độ của Inspector
Gói npm cung cấp binary chính là mcp-inspector. Web là chế độ mặc định:
npx @modelcontextprotocol/inspector # web UI (default)
npx @modelcontextprotocol/inspector --cli # CLI
npx @modelcontextprotocol/inspector --tui # TUI
npx -p @modelcontextprotocol/inspector mcpdo --help # mcpdoLệnh đầu mở Web UI mặc định. Thêm --cli để dùng CLI và --tui để mở giao diện terminal. Lệnh cuối hiển thị trợ giúp của binary mcpdo, một CLI thử nghiệm riêng trong cùng package.
Nếu chạy từ mã nguồn sau khi build, README có các script launcher sau:
npm run web # prod web launcher against clients/web/dist
npm run web:dev # web launcher in --dev mode (Vite)npm run web dùng bản Web đã build trong clients/web/dist. npm run web:dev chạy launcher ở chế độ phát triển với Vite. Nếu bạn quên npm run build, các script dựa trên launcher có thể không có đủ file đầu ra.
IV.Kiểm tra đã chạy được chưa
Cách kiểm tra nhanh nhất là chạy lệnh Web mặc định:
npx @modelcontextprotocol/inspectorKết quả mong đợi là Web UI của Inspector khởi động. Nếu muốn kiểm tra các chế độ còn lại, chạy:
npx @modelcontextprotocol/inspector --cli
npx @modelcontextprotocol/inspector --tui
npx -p @modelcontextprotocol/inspector mcpdo --helpVới bản cài từ source, một lần build thành công được xem là dấu hiệu các phần Web, CLI, TUI và launcher đã được build theo chuỗi của repo:
npm run buildNếu bạn đang phát triển Web, lệnh sau phải khởi động được Vite và vòng lặp HMR:
cd clients/web && npm run devĐể kiểm tra MCP server trong thực tế, quy trình được repo mô tả là kết nối, liệt kê, gọi rồi kiểm tra kết quả. Với smoke test bằng shell hoặc CI, tài liệu của repo đề cập đến --format json, jq và mã thoát. Tư liệu hiện có không cung cấp đầy đủ câu lệnh kết nối cụ thể, nên bạn cần xem hướng dẫn MCP server configuration hoặc smoke-testing trong thư mục tài liệu của repo.
V.Dùng vào việc thật
A.Dev kiểm tra MCP server trước khi tích hợp
Một lập trình viên vừa viết xong MCP server có thể mở Web UI để kiểm tra kết nối và xem server phản hồi ra sao. Bắt đầu bằng:
npx @modelcontextprotocol/inspectorSau đó dùng cấu hình MCP server của dự án trong Inspector. Mục tiêu là xác nhận server kết nối được, có thể liệt kê các thành phần cần thiết và gọi thử trước khi đưa vào ứng dụng khác. Định dạng cấu hình cụ thể cần xem trong tài liệu của repo.
B.Đội kỹ thuật chạy kiểm tra trong CI
Khi cần kiểm tra lặp lại, dùng chế độ CLI thay vì thao tác thủ công trên Web:
npx @modelcontextprotocol/inspector --cliRepo mô tả quy trình shell hoặc CI gồm kết nối, list, call và assert. Tài liệu cũng đề cập đến đầu ra --format json, có thể kết hợp với jq, cùng bản đồ mã thoát để job CI biết bước nào thất bại. Bạn nên lấy cú pháp đầy đủ từ tài liệu smoke-testing của repo trước khi viết script chính thức.
C.Dev làm việc trên máy không tiện mở trình duyệt
Nếu đang dùng terminal hoặc SSH, TUI là lựa chọn phù hợp:
npx @modelcontextprotocol/inspector --tuiTUI dùng Ink và React để cung cấp giao diện tương tác trong terminal. Bạn có thể kiểm tra server trong cùng môi trường đang chạy code mà không cần chuyển sang cửa sổ trình duyệt. Với phiên SSH hoặc máy headless, cần đặc biệt lưu ý cách lưu secrets vì môi trường này có thể không có OS keychain.
D.Tác vụ cần giữ một kết nối để gọi nhiều lần
Nếu bạn có một phiên cần gọi nhiều lệnh trên cùng MCP server, có thể xem xét mcpdo:
npx -p @modelcontextprotocol/inspector mcpdo --helpmcpdo là CLI thử nghiệm, cho phép kết nối một lần rồi chạy nhiều lệnh trên connection có tên thông qua daemon cục bộ. Hãy đọc trợ giúp và tài liệu riêng trong clients/mcpdo để biết cú pháp đầy đủ trước khi đưa vào quy trình tự động.
Kiểm thử tốt là biến một MCP server từ “có vẻ chạy” thành “đã kết nối, đã gọi và đã kiểm tra kết quả”.
Ông T
Inspector có thể xử lý OAuth token, OAuth client secret và giá trị stdio env.
Hãy kiểm tra nơi lưu secrets trước khi chạy trên máy dùng chung, phiên SSH hoặc container.
File ~/.mcp-inspector/secrets.json có thể không được mã hoá nếu không cung cấp key.
VI.Lỗi hay gặp và cách xử lý
A.Node không đúng phiên bản
package.json chỉ hỗ trợ ^22.23.4 || ^24.22.1 || >=26.12.1. Nếu Node thấp hơn hoặc thuộc dòng không phù hợp, npm install, build hoặc chạy binary có thể lỗi. Hãy đổi sang phiên bản được hỗ trợ rồi chạy lại cài đặt tại repo; không nên bỏ qua engine bằng các cờ chưa được README hướng dẫn.
B.Chạy launcher trước khi build
Các script launcher chạy bản launcher đã build. Nếu bạn chạy npm run web hoặc npm run web:dev khi chưa build, có thể thiếu đầu ra cần thiết. Hãy chạy:
npm run buildSau đó chạy lại script phù hợp.
C.Cài npm ở sai thư mục
README yêu cầu npm install tại repo root. Nếu chạy trong thư mục khác, postinstall có thể không cài dependency cho các client. Hãy quay về thư mục chứa package.json gốc rồi chạy lại lệnh.
D.Không có keychain để lưu secrets
Linux thiếu libsecret hoặc Secret Service, phiên SSH headless và container có thể khiến Inspector dùng ~/.mcp-inspector/secrets.json. File này có thể lưu secrets không mã hoá nếu bạn không cung cấp key. Hãy xem tài liệu Where secrets are stored để chọn keychain, mã hoá file hoặc chỉ lưu trong bộ nhớ.
E.Dùng cờ của v1 cho bản v2
README cảnh báo v2 có thay đổi về CLI flags, tách --config và --catalog, cùng thay đổi về Node engine. Nếu bạn nâng cấp từ v1 và lệnh cũ không còn chạy, hãy đọc hướng dẫn migration v1 → v2 và kiểm tra nhánh hoặc tag bạn đang dùng.
VII.Có nên dùng không
Nên dùng MCP Inspector nếu bạn đang phát triển hoặc vận hành MCP server và cần cả giao diện kiểm tra thủ công lẫn cách chạy tự động trong CI. Việc có Web, CLI và TUI trong cùng một package giúp đội kỹ thuật chọn cách làm phù hợp với từng hoàn cảnh. Quy trình kiểm tra kết nối, liệt kê, gọi và assert cũng phù hợp để biến kiểm tra ad-hoc thành smoke test lặp lại.
Điểm mạnh khác là repo có nhiều tài liệu chuyên biệt: cấu hình MCP server, Docker, HTTPS, secrets, smoke testing và migration. Dự án cũng có cấu trúc rõ ràng với client Web, CLI, mcpdo, TUI, launcher và phần core dùng chung.
Giới hạn là yêu cầu Node khá cụ thể, v2 không phải npm workspace và mỗi client có cấu trúc dependency riêng. mcpdo vẫn được đánh dấu là thử nghiệm. Tư liệu được cung cấp cũng chưa nêu chi tiết cú pháp cấu hình server hay toàn bộ lệnh smoke test, nên người mới có thể cần đọc thêm README của từng client và thư mục docs/.
Nếu bạn chỉ cần gọi một MCP server một lần và đã có công cụ tích hợp sẵn, Inspector có thể hơi nhiều tính năng. Nếu bạn cần debug, kiểm thử lặp lại, chạy CI hoặc quan sát nhiều loại kết nối, đây là lựa chọn đáng cân nhắc. Hãy đặc biệt kiểm tra chính sách lưu secrets trước khi dùng trên máy dùng chung hoặc trong container.
Câu hỏi thường gặp
MCP Inspector có miễn phí không?
Tư liệu được cung cấp không nêu rõ chính sách miễn phí hay chi phí sử dụng. Repo có package npm `@modelcontextprotocol/inspector`, nhưng chưa có thông tin đầy đủ để kết luận về chi phí.
Có cần GPU để chạy MCP Inspector không?
Tư liệu không yêu cầu GPU. Repo chỉ nêu yêu cầu Node theo các dòng được hỗ trợ và các cách chạy Web, CLI, TUI hoặc mcpdo.
Có chạy được trên Windows không?
Tư liệu không nêu danh sách hệ điều hành được hỗ trợ nên chưa thể khẳng định riêng về Windows. Công cụ chạy trên Node và README có nhắc đến các môi trường Linux, SSH, Termux và container trong phần lưu secrets.
MCP Inspector dùng để làm gì?
Đây là công cụ kiểm tra MCP server. Nó có Web UI, CLI, TUI và mcpdo để kết nối, kiểm tra, gọi thử và tự động hoá việc kiểm thử server.
Secrets được lưu ở đâu?
Inspector mặc định dùng OS keychain nếu có thể. Trong môi trường không có keychain, secrets có thể được lưu tại `~/.mcp-inspector/secrets.json`, có thể không mã hoá nếu bạn không cung cấp key.
Có thể dùng MCP Inspector trong CI không?
Có. README mô tả CLI dành cho automation và CI, cùng quy trình smoke test dùng đầu ra JSON, `jq` và mã thoát. Tư liệu hiện có chưa cung cấp đầy đủ câu lệnh smoke test cụ thể.
mcpdo khác gì CLI chính?
CLI chính chạy qua binary `mcp-inspector` và có thể dùng cho automation. mcpdo là CLI thử nghiệm, cho phép kết nối một lần rồi chạy nhiều lệnh trên connection có tên thông qua daemon cục bộ.


