MCP Inspector: kiểm thử máy chủ MCP bằng web, CLI, TUI — hướng dẫn cài đặt và dùng
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 →

Tóm tắt nhanh
MCP Inspector là công cụ dành cho lập trình viên để kiểm tra, gỡ lỗi và kiểm thử máy chủ MCP (Model Context Protocol). Gói npm @modelcontextprotocol/inspector có bốn cách dùng: web, CLI, TUI và mcpdo (thử nghiệm). Chỉ cần Node đủ mới là chạy được bằng npx, không phải cài gì thêm.
MCP Inspector là bộ công cụ dành cho lập trình viên để kiểm tra các máy chủ MCP (Model Context Protocol). Nó đóng gói trong một gói npm duy nhất là @modelcontextprotocol/inspector, và cho bạn bốn cách soi một máy chủ: giao diện web, dòng lệnh (CLI), giao diện trong terminal (TUI) và một công cụ thử nghiệm tên mcpdo.
Nếu bạn đang viết một máy chủ MCP, hoặc đang dùng máy chủ MCP của người khác và muốn biết nó thực sự cung cấp những gì, thì đây là chỗ để nhìn tận mắt. Thay vì cắm máy chủ vào một trợ lý AI rồi đoán xem tại sao nó không chạy, bạn kết nối thẳng bằng Inspector, xem danh sách công cụ và gọi thử từng cái. Người làm kinh doanh hay văn phòng không viết code thì ít khi cần đến nó. Nó hợp nhất với dev mới và người phải kiểm tra chất lượng máy chủ MCP.
Điểm đáng giá nhất: bạn chạy được ngay bằng một dòng npx, không cần clone repo. Một tính năng nữa là bản CLI chạy được trong script và CI, nên việc kiểm thử không còn phải bấm tay. Repo hiện có khoảng 11.288 sao và 1.569 fork, và vẫn được cập nhật trong 3 tháng gần đây.
modelcontextprotocol/inspector
MCP Inspector là bộ công cụ chính thức để kiểm tra máy chủ MCP, có giao diện web, dòng lệnh (CLI) và giao diện terminal (TUI), chạy được bằng một lệnh npx.
I.MCP Inspector làm được gì
Cả bốn cách dùng đều nằm trong cùng một gói. Bạn chọn cách hợp với việc mình đang làm.
A.Giao diện web
Đây là chế độ mặc định khi bạn chạy lệnh không kèm cờ nào. Nó là một ứng dụng một trang xây bằng Vite, React và Mantine, có phần backend chạy bằng Node. Cách này hợp nhất cho người mới, vì bạn bấm chuột để xem và thử, không cần nhớ cú pháp lệnh.
B.CLI để tự động hoá
Chế độ --cli là một client dòng lệnh dùng được trong script, CI và các vòng lặp phản hồi nhanh của AI agent. Tài liệu trong repo có hẳn một hướng dẫn về quy trình kết nối, liệt kê, gọi thử rồi kiểm tra kết quả cho shell hoặc CI. Hướng dẫn đó nhắc đến việc xuất --format json rồi lọc bằng jq, bảng mã thoát (exit code), và cách giữ OAuth không đòi tương tác. Lợi ích thực tế là bạn có thể gắn bước kiểm tra máy chủ MCP vào quy trình build, lỗi là biết ngay.
C.TUI trong terminal
Chế độ --tui là giao diện tương tác ngay trong cửa sổ terminal, xây bằng Ink. Nó hợp khi bạn làm việc qua SSH hoặc không muốn mở trình duyệt.
D.mcpdo (thử nghiệm)
mcpdo là công cụ kết nối: bạn kết nối một lần, đặt tên cho kết nối, rồi chạy nhiều lệnh trên kết nối đó thông qua một tiến trình nền cục bộ ngầm. README đánh dấu nó là thử nghiệm, nên đừng dựa vào nó cho việc quan trọng. Repo còn có thư mục skills/mcpdo, là skill dạy một AI agent biết cách dùng mcpdo.
E.Quản lý bí mật
Inspector xử lý token OAuth, client secret OAuth và các giá trị env: của máy chủ stdio. Mặc định chúng được lưu trong keychain của hệ điều hành nếu có. Nếu máy không có keychain thì chúng được lưu vào file ~/.mcp-inspector/secrets.json, và file này không mã hoá trừ khi bạn cung cấp khoá. Mình sẽ nhắc lại điểm này ở phần lưu ý an toàn.
II.Cần chuẩn bị gì
Tư liệu của repo nói khá ít về điều kiện chạy, nên mình chỉ ghi những gì có:
- Node.js:
package.jsonyêu cầu^22.23.4 || ^24.22.1 || >=26.12.1. README gọi đây là bản đã vá trên mỗi dòng được hỗ trợ. Bạn nên kiểm tra phiên bản Node của mình trước, vì bản quá cũ là nguyên nhân lỗi phổ biến nhất. - Một máy chủ MCP để kiểm tra: Inspector là công cụ soi máy chủ, nên bạn cần có máy chủ để nó kết nối. Cách khai báo máy chủ nằm trong tài liệu “MCP server configuration” của repo (thư mục
docs/). - Tài khoản, API key, GPU: README không yêu cầu cái nào trong số này. Nếu máy chủ bạn muốn kiểm tra tự đòi key hoặc OAuth thì đó là chuyện của máy chủ đó.
- Hệ điều hành: README không liệt kê hệ điều hành được hỗ trợ. Phần cảnh báo có nhắc Linux, SSH, Termux và container, tức là công cụ được tính đến trên nhiều môi trường. Riêng việc chạy trên Windows thì tư liệu chưa nói rõ.
- Để phát triển từ mã nguồn: cần thêm Git, vì bạn phải clone repo.
III.Cài đặt từng bước
Bạn có hai hướng. Hướng một là chạy thẳng bằng npx, không cài gì, hợp với 95% người dùng. Hướng hai là clone repo để chạy từ mã nguồn, chỉ dành cho người muốn sửa hoặc đóng góp.
- Kiểm tra NodeBảo đảm Node đúng phiên bản yêu cầu
- Mở terminalMở PowerShell, Terminal hoặc cửa sổ lệnh bất kỳ
- Chạy bằng npxGõ một lệnh để mở giao diện web mặc định
- Chọn chế độ khácThêm --cli hoặc --tui nếu cần
- (Tuỳ chọn) Chạy từ mã nguồnClone repo, cài và build để phát triển
A.Kiểm tra Node
Mở terminal và xem phiên bản Node. Lệnh node --version là lệnh phổ thông của Node, không nằm trong README nhưng chắc chắn đúng.
node --versionSo kết quả với yêu cầu ^22.23.4 || ^24.22.1 || >=26.12.1. Nếu thấp hơn, bạn cần nâng Node lên trước khi làm tiếp.
B.Mở terminal ở đâu
Với cách chạy bằng npx, bạn mở terminal ở thư mục nào cũng được, vì không phải clone gì. Trên Windows, bạn dùng PowerShell hoặc Windows Terminal đều ổn.
C.Chạy bằng npx
Đây là lệnh mặc định, mở giao diện web:
npx @modelcontextprotocol/inspectornpx sẽ tải gói về rồi chạy ngay. Lần đầu có thể hơi lâu vì phải tải. Chỗ người mới hay vấp là chờ mà không thấy gì: hãy đợi terminal in xong thông tin, rồi làm theo những gì nó hiển thị.
D.Chọn chế độ khác
Các chế độ còn lại chạy bằng cùng một gói, chỉ khác cờ:
npx @modelcontextprotocol/inspector --cli # CLI
npx @modelcontextprotocol/inspector --tui # TUI
npx -p @modelcontextprotocol/inspector mcpdo --help # mcpdoLệnh mcpdo --help chỉ in phần trợ giúp. Muốn biết mcpdo kết nối thế nào, xem clients/mcpdo/README.md trong repo.
E.(Tuỳ chọn) Chạy từ mã nguồn
Phần này dành cho người muốn phát triển. Bạn clone repo, vào thư mục rồi cài và build theo README:
git clone https://github.com/modelcontextprotocol/inspector.git
cd inspector
npm install # at the repo root; postinstall cascades into every client
npm run build # web → cli → tui → launcherSau khi build xong, bạn chạy giao diện web đã build bằng:
npm run web # prod web launcher against clients/web/dist
npm run web:dev # web launcher in --dev mode (Vite)Nếu chỉ làm việc với giao diện web và muốn tải lại nhanh khi sửa code, README gợi ý chạy Vite trực tiếp:
cd clients/web && npm run devLưu ý: các script chạy launcher cần build trước, nên đừng bỏ qua npm run build. Ngoài ra repo không phải npm workspace, mỗi client trong clients/* có package.json và node_modules riêng.
Inspector quản lý bí mật như token OAuth, client secret và giá trị env của máy chủ stdio. Trên máy không có keychain (Linux không có libsecret, phiên SSH, Termux, container có gắn volume), chúng được ghi vào ~/.mcp-inspector/secrets.json và không mã hoá nếu bạn không cấp khoá. Đừng dùng key thật của hệ thống quan trọng trên máy dùng chung, và đừng đưa file này vào Git.
IV.Kiểm tra đã chạy được chưa
Tư liệu không mô tả chính xác màn hình hay dòng chữ in ra khi chạy thành công, nên mình chỉ nói những dấu hiệu hợp lý theo cách công cụ được thiết kế:
- Với giao diện web: sau lệnh
npx @modelcontextprotocol/inspector, terminal không báo lỗi và giữ tiến trình đang chạy. Giao diện được phục vụ cho bạn mở trong trình duyệt. Bạn đọc dòng terminal in ra để biết địa chỉ cần mở. - Với CLI hoặc
mcpdo: cách nhanh nhất là xem trợ giúp. Lệnhnpx -p @modelcontextprotocol/inspector mcpdo --helpin ra phần hướng dẫn nếu gói chạy được. - Với bản chạy từ mã nguồn:
npm run buildkết thúc không lỗi là dấu hiệu tốt. README còn cónpm run validate(định dạng, lint, kiểm tra kiểu, build và test đơn vị) để chắc chắn hơn. Lệnh này dành cho dev và có thể chạy khá lâu.
Thử thực tế nhất vẫn là kết nối một máy chủ MCP bạn biết rõ và xem Inspector có liệt kê đúng các công cụ của nó hay không.
V.Dùng vào việc thật
A.Dev mới viết máy chủ MCP đầu tiên
Bạn vừa viết xong một máy chủ MCP nhỏ và không biết nó có “nói” đúng giao thức không. Chạy giao diện web bằng npx @modelcontextprotocol/inspector, khai báo máy chủ của bạn, rồi xem nó liệt kê những gì. Bạn thử gọi từng công cụ và nhìn kết quả trả về ngay trên màn hình. Bạn tìm ra lỗi mà không cần cắm vào một trợ lý AI rồi đoán mò.
Cách khai báo máy chủ (file cấu hình, định dạng) nằm trong tài liệu “MCP server configuration” ở thư mục docs/. Mình không chép lệnh kết nối ở đây vì README chính không ghi, bạn xem trực tiếp tài liệu đó.
Muốn biết máy chủ MCP có làm đúng không, hãy gọi thử nó trước, đừng đoán qua AI.
Ông T
B.Kỹ sư gắn bước kiểm tra vào CI
Bạn có một máy chủ MCP nội bộ và muốn mỗi lần đẩy code đều tự kiểm tra rằng nó vẫn kết nối được và các công cụ vẫn còn. Dùng chế độ --cli: chạy npx @modelcontextprotocol/inspector --cli với các tham số phù hợp, lấy kết quả dạng JSON, lọc bằng jq, và dựa vào mã thoát để quyết định bước CI đạt hay hỏng.
Chi tiết từng tham số nằm trong tài liệu “Smoke-testing an MCP server” của repo. Kết quả bạn nhận được là một bước kiểm tra lặp lại được, thay cho việc ai đó mở giao diện và bấm tay mỗi lần.
C.Người làm việc qua SSH hoặc trên máy chủ không có trình duyệt
Bạn đang đăng nhập vào một máy chủ từ xa, không có giao diện đồ hoạ, nhưng cần xem máy chủ MCP trên đó đang cung cấp gì. Chạy npx @modelcontextprotocol/inspector --tui để có giao diện tương tác ngay trong terminal. Bạn xem và thử công cụ mà không phải mở cổng ra ngoài hay cài thêm trình duyệt.
Nếu máy đó không có keychain, nhớ lại cảnh báo ở trên về secrets.json.
D.Người dùng AI agent muốn agent tự kiểm tra máy chủ
Bạn dùng một AI agent như Claude Code và muốn nó tự gọi thử máy chủ MCP rồi báo kết quả. Repo có thư mục skills/mcpdo là skill dạy agent dùng mcpdo, và docs/ có hướng dẫn “Reviewing an MCP App” theo kiểu CLI trước, rồi mới mở web một lần. mcpdo đang ở trạng thái thử nghiệm, nên hãy coi đây là hướng để thử, không phải để dựa vào hoàn toàn.
VI.Lỗi hay gặp và cách xử lý
A.Báo lỗi hoặc không chạy vì Node quá cũ
Đây là lỗi dễ xảy ra nhất. Repo yêu cầu ^22.23.4 || ^24.22.1 || >=26.12.1. Chạy node --version, nếu thấp hơn thì nâng Node lên bản phù hợp rồi chạy lại lệnh npx.
B.npm run web không chạy được từ mã nguồn
Các script launcher chạy bản đã build, nên bạn phải chạy npm run build trước. Nếu quên bước này, launcher sẽ không có gì để chạy. Muốn làm việc nhanh với giao diện web thì dùng cd clients/web && npm run dev.
C.Máy chủ cần HTTPS hoặc dùng chứng chỉ tự ký
Tài liệu của repo có hai mục liên quan: “Serving the web UI over HTTPS” (các biến INSPECTOR_TLS_KEY_PATH và INSPECTOR_TLS_CERT_PATH) và “Environment variables” (có nhắc các biến TLS của Node cho máy chủ tự ký). Nếu bạn gặp lỗi chứng chỉ, đọc hai tài liệu này, đừng tắt kiểm tra bảo mật một cách bừa bãi.
D.Bí mật bị lưu ở file không mã hoá
Trên máy không có keychain, token và secret nằm trong ~/.mcp-inspector/secrets.json. Cách xử lý an toàn: xem tài liệu “Where secrets are stored” để lấy lại keychain, mã hoá file, hoặc giữ bí mật chỉ trong bộ nhớ. Trước khi làm, đừng chia sẻ thư mục home hoặc ảnh chụp của máy này.
E.Dùng cờ cũ của v1 mà không chạy
Repo này là dòng v2. README có nhắc hướng dẫn chuyển từ v1 sang v2 vì cờ CLI đã đổi, có thêm tách --config và --catalog, và yêu cầu Node cao hơn. Nếu bạn đang theo một bài hướng dẫn cũ, cờ trong đó có thể không còn đúng. Cần bản v1 thì README ghi lệnh: npx @modelcontextprotocol/inspector@v1-latest, nhưng bản này chỉ nhận bản vá bảo mật.
VII.Có nên dùng không
Điểm mạnh. Đây là công cụ do chính dự án MCP phát triển, nên bám sát giao thức. Bạn có một gói, bốn cách dùng, và chạy được ngay bằng npx. Bản CLI giúp tự động hoá kiểm thử. Repo còn có tài liệu chi tiết, được cập nhật gần đây, và có số sao khá lớn so với các công cụ cùng loại.
Giới hạn. Đây là công cụ cho lập trình viên, không dành cho người chỉ muốn dùng AI trong công việc văn phòng. mcpdo còn thử nghiệm. README không nêu rõ hệ điều hành được hỗ trợ ngoài những gì phần cảnh báo gợi ý. Công cụ giữ bí mật của bạn, nên cần cẩn thận về nơi lưu. Repo nhận đóng góp dưới dạng issue, không nhận pull request từ bên ngoài.
Giấy phép. README ghi dự án MCP đang chuyển từ MIT sang Apache-2.0, nên code mới theo Apache-2.0, còn phần đã cấp theo MIT mà chưa được đồng ý cấp lại vẫn giữ MIT. Nếu bạn dùng trong sản phẩm thương mại, hãy đọc file LICENSE trong repo.
Khi nào chọn cách khác. Nếu bạn chỉ muốn dùng một máy chủ MCP có sẵn trong trợ lý AI của mình, bạn không cần Inspector. Nếu bạn đang ở dòng v1 và chỉ cần sửa lỗi nhỏ, hướng dẫn chuyển đổi sẽ giúp bạn quyết định có nâng cấp hay không.
Câu hỏi thường gặp
MCP Inspector là gì, dùng để làm gì?
Đây là công cụ cho lập trình viên để kiểm tra các máy chủ MCP (Model Context Protocol). Nó có bốn cách dùng: giao diện web, CLI, TUI và mcpdo (thử nghiệm). Bạn dùng nó để xem máy chủ cung cấp gì và gọi thử trước khi cắm vào ứng dụng khác.
MCP Inspector có miễn phí không?
README không nói về giá hay gói trả phí, và gói chạy được bằng npx. Về giấy phép, README ghi dự án MCP đang chuyển từ MIT sang Apache-2.0, chi tiết nằm trong file LICENSE của repo. Bạn nên đọc file đó nếu định dùng thương mại.
Cần cài những gì để chạy?
Cần Node đúng phiên bản: ^22.23.4 || ^24.22.1 || >=26.12.1. Sau đó chạy lệnh npx @modelcontextprotocol/inspector là mở được giao diện web mà không phải clone repo. Muốn chạy từ mã nguồn thì cần thêm Git.
Có cần GPU hay API key không?
README không yêu cầu GPU hay API key cho chính Inspector. Nếu máy chủ MCP bạn muốn kiểm tra đòi key hoặc OAuth thì bạn phải cung cấp theo yêu cầu của máy chủ đó.
Chạy được trên Windows không?
Tư liệu chưa nêu rõ danh sách hệ điều hành được hỗ trợ. Công cụ chạy bằng Node và npx nên về nguyên tắc cần Node đủ mới. Bạn nên tự thử lệnh npx trong PowerShell và đọc tài liệu trong repo nếu gặp lỗi.
Dữ liệu và bí mật của tôi có an toàn không?
Mặc định Inspector lưu token OAuth, client secret và giá trị env của máy chủ stdio trong keychain của hệ điều hành nếu có. Nếu máy không có keychain, chúng nằm trong ~/.mcp-inspector/secrets.json và không mã hoá trừ khi bạn cung cấp khoá. Tài liệu “Where secrets are stored” trong repo hướng dẫn mã hoá hoặc giữ bí mật trong bộ nhớ.
Nên dùng giao diện web, CLI hay TUI?
Người mới nên bắt đầu với giao diện web vì có thể bấm chuột để xem và thử. CLI hợp để tự động hoá trong script hoặc CI. TUI hợp khi bạn làm việc trong terminal hoặc qua SSH.


