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

MCP Inspector: kiểm thử máy chủ MCP bằng web, CLI, TUI — hướng dẫn cài đặt và dùng

11 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ử máy chủ MCP bằng web, CLI, TUI — 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.

CLI

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.

★ 11kTypeScript
Xem repo trên GitHub

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.json yê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.

  1. Kiểm tra NodeBảo đảm Node đúng phiên bản yêu cầu
  2. Mở terminalMở PowerShell, Terminal hoặc cửa sổ lệnh bất kỳ
  3. Chạy bằng npxGõ một lệnh để mở giao diện web mặc định
  4. Chọn chế độ khácThêm --cli hoặc --tui nếu cần
  5. (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.

Terminal
node --version

So 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:

Terminal
npx @modelcontextprotocol/inspector

npx 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ờ:

Terminal
npx @modelcontextprotocol/inspector --cli             # CLI
npx @modelcontextprotocol/inspector --tui             # TUI
npx -p @modelcontextprotocol/inspector mcpdo --help   # mcpdo

Lệ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:

Terminal
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 → launcher

Sau khi build xong, bạn chạy giao diện web đã build bằng:

Terminal
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:

Terminal
cd clients/web && npm run dev

Lư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ệnh npx -p @modelcontextprotocol/inspector mcpdo --help in 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 build kế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.

4.5/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 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.

Chuyển nhanh tới mục

  1. I.MCP Inspector làm được gì
    1. A.Giao diện web
    2. B.CLI để tự động hoá
    3. C.TUI trong terminal
    4. D.mcpdo (thử nghiệm)
    5. E.Quản lý bí mật
  2. II.Cần chuẩn bị gì
  3. III.Cài đặt từng bước
    1. A.Kiểm tra Node
    2. B.Mở terminal ở đâu
    3. C.Chạy bằng npx
    4. D.Chọn chế độ khác
    5. E.(Tuỳ chọn) Chạy từ mã nguồn
  4. IV.Kiểm tra đã chạy được chưa
  5. V.Dùng vào việc thật
    1. A.Dev mới viết máy chủ MCP đầu tiên
    2. B.Kỹ sư gắn bước kiểm tra vào CI
    3. C.Người làm việc qua SSH hoặc trên máy chủ không có trình duyệt
    4. D.Người dùng AI agent muốn agent tự kiểm tra máy chủ
  6. VI.Lỗi hay gặp và cách xử lý
    1. A.Báo lỗi hoặc không chạy vì Node quá cũ
    2. B.npm run web không chạy được từ mã nguồn
    3. C.Máy chủ cần HTTPS hoặc dùng chứng chỉ tự ký
    4. D.Bí mật bị lưu ở file không mã hoá
    5. E.Dùng cờ cũ của v1 mà không chạy
  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ỏ.