Bỏ qua tới nội dung
Ông T.vn

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

12 phút đọcCập nhật

Bài này là một góc nhìn khác về modelcontextprotocol/inspector — repo từng đổi tên nên mình viết lại với cách tiếp cận khác. Bài hướng dẫn chính: MCP Inspector: kiểm thử MCP server — hướng dẫn cài đặt và dùng →

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ụ TypeScript giúp kết nối, kiểm tra và gọi MCP server qua Web, CLI hoặc giao diện terminal. Bạn có thể chạy nhanh bằng npx; nếu phát triển repo thì cần Node đúng phiên bản và chạy npm install.

MCP Inspector là công cụ dành cho việc kiểm tra và gỡ lỗi các MCP server. Nó cho phép bạn kết nối tới server, xem các tool và tài nguyên mà server cung cấp, gọi thử chúng, rồi dùng kết quả để xác nhận server hoạt động đúng.

Repo này phù hợp với lập trình viên xây MCP server, đội ngũ muốn kiểm thử trong CI, hoặc người cần quan sát nhanh một server trước khi đưa vào quy trình AI. Điểm đáng giá nhất là một gói npm cung cấp nhiều cách làm việc: giao diện Web dễ quan sát, CLI phù hợp tự động hoá, TUI chạy ngay trong terminal, và mcpdo thử nghiệm cho các phiên kết nối kéo dài.

Hiện repo có khoảng 11288 sao và 1570 fork. Dự án vẫn đang được cập nhật, mã nguồn chính viết bằng TypeScript.

CLI

modelcontextprotocol/inspector

Công cụ Web, CLI và TUI để kiểm tra, gỡ lỗi và tự động hoá kiểm thử MCP server.

★ 11kTypeScript
Xem repo trên GitHub

I.MCP Inspector làm được gì

A.Quan sát MCP server bằng giao diện Web

Chế độ Web mở một ứng dụng React chạy trên trình duyệt, đi kèm backend Node. Đây là lựa chọn dễ bắt đầu nếu bạn muốn xem cấu hình, danh sách tool và kết quả gọi tool bằng giao diện trực quan.

Với người mới, Web giúp giảm việc phải nhớ nhiều tham số dòng lệnh. Với người phát triển server, đây là cách thuận tiện để thử từng chức năng và phát hiện lỗi trong dữ liệu trả về.

B.Gọi MCP server bằng CLI

CLI được thiết kế cho các lệnh có thể lặp lại, tự động hoá và chạy trong CI. Bạn có thể dùng nó để kết nối server, liệt kê khả năng, gọi tool và lấy đầu ra ở định dạng phù hợp với bước kiểm tra tiếp theo.

README cũng mô tả quy trình smoke test theo hướng kết nối, liệt kê, gọi và kiểm tra kết quả. Khi dùng --format json kết hợp với jq, một shell script có thể tự xác nhận đầu ra thay vì cần người nhìn màn hình.

C.Làm việc trong terminal bằng TUI

TUI là giao diện tương tác chạy trong terminal, xây dựng với Ink. Nó phù hợp khi bạn đang làm việc qua SSH, thích bàn phím, hoặc không muốn mở trình duyệt riêng.

TUI vẫn được khởi chạy qua binary chính mcp-inspector, nên bạn không phải cài một công cụ hoàn toàn khác cho từng kiểu giao diện.

D.Duy trì một kết nối với mcpdo

mcpdo là CLI kết nối thử nghiệm. Ý tưởng của nó là kết nối một lần, sau đó chạy nhiều lệnh trên kết nối đã đặt tên thông qua một daemon cục bộ ngầm.

Cách này có thể hữu ích khi bạn cần thực hiện nhiều thao tác liên tiếp trên cùng MCP server. Vì đây là tính năng experimental, bạn nên kiểm tra tài liệu riêng trong clients/mcpdo trước khi dùng cho quy trình quan trọng.

E.Hỗ trợ kiểm thử lặp lại trong dự án

Repo có các thư mục test-servers và scripts dành cho server kiểm thử, fixture, smoke test và các bước xác minh. Phần này có ích cho đội phát triển muốn biến các thao tác kiểm tra thủ công thành quy trình có thể chạy lại.

F.Quản lý thông tin bí mật

Inspector có thể xử lý OAuth token, OAuth client secret và giá trị trong stdio env:. Theo README, công cụ ưu tiên lưu chúng trong keychain của hệ điều hành nếu có.

Nếu máy không có keychain phù hợp, chẳng hạn Linux thiếu libsecret hoặc Secret Service, phiên SSH không có giao diện, Termux hoặc container có volume gắn ngoài, secret có thể được lưu vào ~/.mcp-inspector/secrets.json. Trong tình huống này, file không được mã hoá nếu bạn không cung cấp key.

Hãy coi token, client secret và giá trị trong stdio env là dữ liệu nhạy cảm. Kiểm tra nơi lưu secret trước khi chạy trong máy dùng chung, phiên SSH hoặc container; không đưa file secrets.json vào kho mã nguồn.

II.Cần chuẩn bị gì

Bạn cần Node.js ở một phiên bản được package hỗ trợ: ^22.23.4 || ^24.22.1 || >=26.12.1. Đây là yêu cầu quan trọng vì npm package có kiểm tra engine.

Nếu chỉ muốn dùng công cụ đã xuất bản, README cho phép chạy trực tiếp bằng npx @modelcontextprotocol/inspector. Khi phát triển hoặc xây repo từ mã nguồn, bạn cần một bản sao repo, npm và terminal.

Nếu làm việc với một MCP server có OAuth hoặc biến môi trường nhạy cảm, bạn cần chuẩn bị thông tin xác thực tương ứng. README không yêu cầu một tài khoản dịch vụ cụ thể cho việc khởi động Inspector, và cũng không nêu yêu cầu GPU.

Repo có cấu hình Docker, tài liệu về chạy Web qua HTTPS, biến môi trường cho cổng, xác thực, proxy, kho secret và TLS. Tuy nhiên, bạn chỉ cần Docker, chứng chỉ hoặc các biến môi trường đó khi chọn đúng kịch bản tương ứng.

README không xác nhận hệ điều hành cụ thể là được hỗ trợ toàn diện. Tài liệu có đề cập đến keychain trên Linux, phiên SSH, Termux và container, nên cách lưu secret có thể thay đổi theo môi trường.

III.Cài đặt từng bước

  1. Chọn cách chạyDùng npx để mở ngay hoặc clone repo để phát triển
  2. Kiểm tra Node.jsDùng một phiên bản thuộc dải engine được hỗ trợ
  3. Cài dependencyChạy npm install tại thư mục gốc nếu làm việc từ mã nguồn
  4. Build dự ánChạy npm run build để tạo các client và launcher
  5. Khởi chạy InspectorChọn Web, CLI hoặc TUI theo nhu cầu

A.Chọn cách chạy nhanh bằng npx

Nếu mục tiêu là kiểm tra một MCP server ngay, bạn không nhất thiết phải clone mã nguồn. Mở terminal và chạy binary chính ở chế độ Web:

Terminal
npx @modelcontextprotocol/inspector

Sau khi lệnh chạy, bạn dùng giao diện Web để làm việc với MCP server. Đây là cách ngắn nhất để bắt đầu vì npm sẽ lấy package và chạy binary.

Bạn cũng có thể chọn CLI hoặc TUI:

Terminal
npx @modelcontextprotocol/inspector --cli
npx @modelcontextprotocol/inspector --tui

Nếu muốn xem trợ giúp của mcpdo, dùng binary thứ hai trong cùng package:

Terminal
npx -p @modelcontextprotocol/inspector mcpdo --help

Người mới thường nhầm mcpdo với một tuỳ chọn của mcp-inspector. README tách chúng thành hai binary, vì vậy lệnh mcpdo dùng dạng npx -p ... mcpdo --help.

B.Clone repo để phát triển

Nếu bạn muốn đọc mã nguồn, sửa client hoặc chạy bộ kiểm tra của repo, clone repo rồi đi vào thư mục:

Terminal
git clone https://github.com/modelcontextprotocol/inspector.git
cd inspector

Mở terminal tại thư mục bạn muốn lưu dự án. Sau lệnh cd inspector, các lệnh npm tiếp theo phải được chạy ở thư mục gốc, nơi có package.json và package-lock.json.

C.Cài dependency và build

Kiểm tra Node.js của bạn trước khi cài. README yêu cầu một trong các dải sau: ^22.23.4 || ^24.22.1 || >=26.12.1.

Tại thư mục gốc, chạy:

Terminal
npm install
npm run build

npm install cài dependency ở repo root và postinstall tiếp tục cài cho từng client. npm run build build theo chuỗi web, CLI, TUI rồi launcher.

Repo v2 không phải npm workspace. Mỗi client trong clients/* có package.json và node_modules riêng. Vì vậy, không nên tự ý xoá hoặc gộp các thư mục dependency của client khi chưa đọc quy tắc trong repo.

D.Chạy Web sau khi build

Launcher-driven script dùng bản build của launcher, nên hãy chạy npm run build trước. Sau đó chọn một trong các lệnh:

Terminal
npm run web
npm run web:dev

npm run web chạy Web launcher ở chế độ production, sử dụng clients/web/dist. npm run web:dev chạy Web launcher ở chế độ --dev và dùng Vite.

Nếu bạn đang sửa giao diện Web hằng ngày, README khuyên chạy Vite trực tiếp để có HMR nhanh:

Terminal
cd clients/web && npm run dev

Lệnh này phải chạy từ thư mục clients/web. Đây là điểm dễ vấp: các lệnh của client không nhất thiết chạy giống lệnh ở thư mục gốc.

E.Chạy các bước kiểm tra của repo

Sau khi cài dependency, bạn có thể chạy vòng kiểm tra nhanh:

Terminal
npm run validate

README mô tả validate gồm kiểm tra format, lint, typecheck, build và unit test. Khi cần kiểm tra coverage, chạy:

Terminal
npm run coverage

Trước khi đẩy thay đổi lên repo, quy trình được README đánh dấu là bắt buộc:

Terminal
npm run local:gate

Lệnh này nối các kiểm tra CI, smoke test và Storybook test. Nó phù hợp với người đang đóng góp mã nguồn hơn là người chỉ muốn dùng Inspector để kiểm tra một server.

IV.Kiểm tra đã chạy được chưa

Cách đơn giản nhất là chạy:

Terminal
npx @modelcontextprotocol/inspector

Nếu Inspector khởi động được giao diện Web, bước chạy cơ bản đã thành công. Bạn có thể tiếp tục chọn hoặc cấu hình MCP server trong giao diện.

Nếu cần kiểm tra CLI, chạy:

Terminal
npx @modelcontextprotocol/inspector --cli

Nếu cần kiểm tra TUI, chạy:

Terminal
npx @modelcontextprotocol/inspector --tui

Với bản clone từ repo, dấu hiệu build thành công là npm run build hoàn tất sau chuỗi web, CLI, TUI và launcher. Với mã nguồn đang sửa, npm run validate phải hoàn tất các bước format, lint, typecheck, build và unit test.

README không đưa ra một MCP server cụ thể để mọi người dùng làm dữ liệu mẫu trong phần Quick start. Vì vậy, nếu bạn chưa có server, hãy đọc thêm cấu hình server trong tài liệu của repo và thư mục test-servers thay vì tự đoán tên server hoặc tham số kết nối.

V.Dùng vào việc thật

A.Dev kiểm tra một MCP server mới

Một lập trình viên vừa viết server có tool tra cứu đơn hàng. Bạn có thể chạy Inspector ở chế độ Web:

Terminal
npx @modelcontextprotocol/inspector

Sau đó kết nối tới server theo cấu hình của dự án, xem danh sách tool, gọi thử tool với dữ liệu kiểm thử và quan sát kết quả. Lợi ích là phát hiện sớm lỗi schema hoặc lỗi dữ liệu trả về trước khi đưa server vào một ứng dụng AI.

B.Đội kỹ thuật kiểm thử trong CI

Một đội muốn xác nhận server còn hoạt động sau mỗi lần thay đổi có thể dùng CLI trong shell hoặc CI. README mô tả quy trình gồm kết nối, liệt kê, gọi và assert, với đầu ra JSON:

Terminal
npx @modelcontextprotocol/inspector --cli --format json

Các tuỳ chọn kết nối và gọi cụ thể phụ thuộc tài liệu CLI hoặc cấu hình server trong repo. Khi đầu ra đã là JSON, bước tiếp theo có thể dùng jq để kiểm tra trường cần thiết và dựa vào exit code để quyết định CI thành công hay thất bại.

C.Nhân viên kỹ thuật cần làm việc qua terminal

Nếu bạn đang ở máy chủ từ xa hoặc thích thao tác bằng bàn phím, chạy:

Terminal
npx @modelcontextprotocol/inspector --tui

TUI cho phép làm việc tương tác ngay trong terminal. Cách này hữu ích khi không thuận tiện mở trình duyệt, nhưng bạn nên để ý cơ chế lưu secret vì phiên SSH có thể không có keychain.

D.Người phát triển cần nhiều lệnh trên một kết nối

Khi cần thực hiện nhiều thao tác trên cùng một kết nối, thử xem mcpdo:

Terminal
npx -p @modelcontextprotocol/inspector mcpdo --help

Đọc hướng dẫn trong clients/mcpdo để biết cú pháp kết nối và lệnh tiếp theo. Vì mcpdo còn experimental, hãy thử ở môi trường phát triển trước khi đưa vào quy trình vận hành.

Công cụ kiểm thử tốt không chỉ cho biết server có trả lời, mà còn giúp bạn chứng minh nó trả lời đúng.

Ông T

VI.Lỗi hay gặp và cách xử lý

A.Node.js không đúng phiên bản

Nếu npm từ chối cài hoặc chạy package, hãy kiểm tra Node.js đang dùng. Inspector yêu cầu ^22.23.4 || ^24.22.1 || >=26.12.1; một phiên bản cũ hơn có thể không đáp ứng engine.

Cách xử lý an toàn là chuyển sang một bản Node thuộc dải được README nêu, sau đó chạy lại npm install. Không nên tự sửa trường engines trong package.json để bỏ qua cảnh báo.

B.Chạy lệnh ở sai thư mục

npm install, npm run build, npm run validate và npm run local:gate là các lệnh dành cho thư mục gốc. Ngược lại, lệnh Vite trong README chạy từ clients/web.

Hãy kiểm tra vị trí terminal trước khi chạy. Nếu bạn đang ở clients/web, quay lại thư mục gốc trước khi chạy script root.

C.Launcher chưa được build

Nếu chạy npm run web hoặc npm run web:dev ngay sau khi clone mà chưa build, launcher có thể chưa có các file cần thiết. README nói rõ launcher-driven scripts chạy bản launcher đã build.

Chạy lại:

Terminal
npm install
npm run build

Sau đó thử script Web lần nữa.

D.Secret bị lưu vào file không mã hoá

Trong môi trường không có keychain, Inspector có thể lưu secret ở ~/.mcp-inspector/secrets.json và file này không được mã hoá nếu bạn không cung cấp key. Điều này dễ xảy ra trong container, phiên SSH hoặc máy Linux thiếu dịch vụ keychain phù hợp.

Đọc tài liệu “Where secrets are stored” trong repo để xem cách bật lại keychain, mã hoá file hoặc chỉ giữ secret trong bộ nhớ. Không chia sẻ file này và không commit nó vào repo.

E.Kết nối OAuth không chạy tự động trong CI

OAuth thường cần token hoặc bước tương tác. README có tài liệu riêng về smoke test và lưu ý giữ OAuth ở chế độ không tương tác khi chạy tự động.

Hãy chuẩn bị thông tin xác thực theo cấu hình server, kiểm tra cách Inspector lưu secret, rồi thiết kế bước CI không chờ thao tác thủ công. Nếu chưa có token hoặc cấu hình rõ ràng, hãy thử trong Web hoặc CLI ở môi trường phát triển trước.

VII.Có nên dùng không

Bạn nên dùng MCP Inspector nếu đang phát triển MCP server và cần một công cụ chung để quan sát, gọi thử, debug hoặc tự động hoá kiểm tra. Ba giao diện Web, CLI và TUI bao phủ khá tốt các nhu cầu từ người mới đến quy trình CI. Việc gom chúng vào một package cũng giúp bạn chuyển từ thử thủ công sang script mà không phải đổi hẳn công cụ.

Điểm mạnh khác là repo có sẵn cấu trúc cho test server, smoke test, tài liệu cấu hình, Docker, HTTPS và kho secret. Dự án cũng đang được cập nhật, nên phù hợp với người muốn theo dõi hệ sinh thái MCP hiện đại.

Giới hạn là yêu cầu Node khá mới, cấu trúc repo v2 có nhiều client và không phải npm workspace nên người mới có thể hơi bối rối khi làm việc từ mã nguồn. mcpdo còn experimental. Cơ chế lưu secret cũng cần được kiểm tra kỹ, nhất là trên máy không có keychain.

Nếu bạn chỉ cần gọi một MCP server một lần và đã có công cụ khách hàng phù hợp, Inspector có thể là quá nhiều. Nếu bạn cần giao diện chuyên biệt cho một server cụ thể, hãy cân nhắc công cụ do chính server đó cung cấp. Còn nếu mục tiêu là kiểm tra có hệ thống, debug nhiều kiểu môi trường hoặc đưa MCP server vào CI, MCP Inspector là lựa chọn đáng thử.

4.3/5 · Ông T chấm

Chưa có độc giả chấm

Bài này có ích với bạn không?

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 xác nhận chính sách giá hoặc mức phí sử dụng. README cho biết công cụ được phát hành qua package npm `@modelcontextprotocol/inspector`, còn thông tin giấy phép cần xem trong file `LICENSE`.

Có cần GPU để chạy MCP Inspector không?

README không nêu yêu cầu GPU. Công cụ gồm Web app với backend Node, CLI và TUI, nên tư liệu chỉ xác nhận yêu cầu Node.js chứ không đưa ra yêu cầu phần cứng đặc biệt.

Có chạy được trên Windows không?

Tư liệu được cung cấp không xác nhận Windows là hệ điều hành được hỗ trợ toàn diện. README có đề cập Linux, SSH, Termux và container trong ngữ cảnh lưu secret, nhưng không đưa hướng dẫn riêng cho Windows.

Dữ liệu và token được lưu ở đâu?

Inspector ưu tiên lưu OAuth token, OAuth client secret và giá trị `stdio env:` trong keychain của hệ điều hành nếu có. Nếu không có keychain, chúng có thể nằm trong `~/.mcp-inspector/secrets.json`; file này không được mã hoá nếu bạn không cung cấp key.

MCP Inspector khác gì một MCP client thông thường?

Inspector tập trung vào việc inspect và kiểm thử MCP server. Nó cung cấp Web, CLI, TUI và mcpdo, trong đó CLI hỗ trợ tự động hoá, CI và vòng phản hồi nhanh cho agent.

Tôi nên dùng Web, CLI hay TUI?

Web phù hợp để quan sát trực quan, CLI phù hợp với script và CI, còn TUI phù hợp khi làm việc tương tác trong terminal. README cũng có `mcpdo` experimental cho trường hợp duy trì một kết nối để chạy nhiều lệnh.

Có thể dùng Inspector để kiểm thử tự động không?

Có. README mô tả CLI dành cho automation và CI, cùng quy trình smoke test kết nối, liệt kê, gọi và assert. Đầu ra `--format json` có thể kết hợp với `jq` trong shell hoặc CI.

Chuyển nhanh tới mục

  1. I.MCP Inspector làm được gì
    1. A.Quan sát MCP server bằng giao diện Web
    2. B.Gọi MCP server bằng CLI
    3. C.Làm việc trong terminal bằng TUI
    4. D.Duy trì một kết nối với mcpdo
    5. E.Hỗ trợ kiểm thử lặp lại trong dự án
    6. F.Quản lý thông tin bí mật
  2. II.Cần chuẩn bị gì
  3. III.Cài đặt từng bước
    1. A.Chọn cách chạy nhanh bằng npx
    2. B.Clone repo để phát triển
    3. C.Cài dependency và build
    4. D.Chạy Web sau khi build
    5. E.Chạy các bước kiểm tra của repo
  4. IV.Kiểm tra đã chạy được chưa
  5. V.Dùng vào việc thật
    1. A.Dev kiểm tra một MCP server mới
    2. B.Đội kỹ thuật kiểm thử trong CI
    3. C.Nhân viên kỹ thuật cần làm việc qua terminal
    4. D.Người phát triển cần nhiều lệnh trên một kết nối
  6. VI.Lỗi hay gặp và cách xử lý
    1. A.Node.js không đúng phiên bản
    2. B.Chạy lệnh ở sai thư mục
    3. C.Launcher chưa được build
    4. D.Secret bị lưu vào file không mã hoá
    5. E.Kết nối OAuth không chạy tự động trong CI
  7. VII.Có nên dùng không

Repo & Skill · 13/11/2026 · 11 phút đọc

Garden Skills: bộ skill thiết kế web, tạo ảnh, làm video cho AI — hướng dẫn cài đặt và dùng

Garden Skills là bộ sưu tập Agent Skills (kỹ năng cho AI) của tác giả ConardLi, dùng được với Claude Code, Cursor, Codex và các AI coding agent khác. Mỗi skill dạy agent làm tốt một việc như thiết kế trang web, tạo ảnh, làm video bằng code, biến tài liệu thành bài viết đẹp. Cài không khó, nhưng README có nhiều cách cài nên bạn cần chọn một cách hợp với công cụ đang dùng.

Repo & Skill · 13/11/2026 · 15 phút đọc

thesysdev/openui: xây giao diện AI dạng streaming — hướng dẫn cài đặt và dùng

OpenUI là framework full-stack, độc lập framework, giúp mô hình AI sinh giao diện có cấu trúc và hiển thị dần khi dữ liệu streaming về. Bạn có thể dựng nhanh một ứng dụng chat bằng CLI hoặc cài từng gói cho React, Vue, Svelte, Angular và LangChain. Việc bắt đầu khá đơn giản nếu máy có đúng phiên bản Node; README chưa ghi đầy đủ lệnh chạy ứng dụng sau khi scaffold.

Repo & Skill · 13/11/2026 · 11 phút đọc

Ruflo: điều phối nhóm agent AI cho Claude Code và Codex — hướng dẫn cài đặt và dùng

Ruflo (trước đây là Claude Flow) là một agent harness: lớp công cụ bao quanh Claude Code và Codex, bổ sung nhiều agent chuyên biệt, bộ nhớ qua các phiên và khả năng chia việc cho nhóm agent. Cài bằng một lệnh `npx ruflo@latest init` trong thư mục dự án, cần Node 20 trở lên. Cài khá dễ, nhưng hệ thống rất rộng nên bạn nên bắt đầu từ một tác vụ nhỏ.