Next.js DevTools MCP

Next.js DevTools MCP

next-devtools-mcp là một máy chủ Model Context Protocol (MCP) kết nối các tác nhân lập trình như Claude và Cursor với máy chủ phát triển Next.js đang chạy của bạn.

Nó là một trình kết nối mỏng. Nó phát hiện các máy chủ phát triển Next.js 16+ đang chạy và ủy quyền điểm cuối MCP tích hợp sẵn của chúng (/_next/mcp) để các tác nhân nhận được lỗi thời gian chạy trực tiếp, tuyến đường và nhật ký. Nó cũng cung cấp hai cổng hướng các tác nhân đến các công cụ mà chúng chạy trực tiếp: tài liệu chính xác theo phiên bản và CLI agent-browser.

[!LƯU Ý] Tài liệu và quy trình di chuyển không còn nằm trong máy chủ này. Next.js đóng gói tài liệu riêng tại node_modules/next/dist/docs/, và các quy trình nâng cấp / Cache Components được phân phối dưới dạng kỹ năng tác nhân. Xem Di chuyển từ 0.3.x.

Yêu cầu

• Node.js v20.19 hoặc phiên bản LTS mới hơn
• npm hoặc pnpm
• Next.js 16+ với máy chủ phát triển đang chạy (cho nextjs_index / nextjs_call)

Cài đặt

Cài đặt cho tất cả các tác nhân lập trình của bạn với add-mcp:

npx add-mcp next-devtools-mcp@latest

Thêm -y để bỏ qua lời nhắc và cài đặt cho tất cả các tác nhân được phát hiện. Thêm -g để cài đặt toàn cục trên tất cả các dự án.

Hoặc thêm cấu hình vào máy khách MCP của bạn theo cách thủ công:

{
  "mcpServers": {
    "next-devtools": {
      "command": "npx",
      "args": ["-y", "next-devtools-mcp@latest"]
    }
  }
}

[!LƯU Ý] next-devtools-mcp@latest giữ máy khách của bạn ở phiên bản mới nhất.

Thiết lập cụ thể cho từng máy khách

amp mcp add next-devtools -- npx next-devtools-mcp@latest

claude mcp add next-devtools npx next-devtools-mcp@latest

codex mcp add next-devtools -- npx next-devtools-mcp@latest

env = { SystemRoot="C:\\Windows", PROGRAMFILES="C:\\Program Files" }
startup_timeout_ms = 20_000

# Project
gemini mcp add next-devtools npx next-devtools-mcp@latest

# Global
gemini mcp add -s user next-devtools npx next-devtools-mcp@latest

{
  "mcpServers": {
    "next-devtools": {
      "command": "npx",
      "args": ["-y", "next-devtools-mcp@latest"]
    }
  }
}

code --add-mcp '{"name":"next-devtools","command":"npx","args":["-y","next-devtools-mcp@latest"]}'

Bắt đầu nhanh

Khởi động máy chủ phát triển Next.js của bạn:

npm run dev

Next.js 16+ kích hoạt điểm cuối MCP của nó theo mặc định tại http://localhost:3000/_next/mcp. next-devtools-mcp phát hiện và kết nối với nó tự động — không cần cấu hình.

Sau đó hỏi tác nhân của bạn về ứng dụng đang chạy:

Next Devtools, what errors are in my Next.js application?
Next Devtools, show me the structure of my routes
Next Devtools, what's in the development server logs?

Tác nhân gọi nextjs_index để phát hiện máy chủ, sau đó nextjs_call để truy vấn trạng thái thực của chúng.

Công cụ

Các cổng không tự thực hiện công việc — chúng cho tác nhân biết tài liệu ở đâu hoặc cách cài đặt/chạy CLI, và tác nhân chạy trực tiếp (nhanh hơn so với ủy quyền qua MCP).

{ "port": 3000, "toolName": "get_errors" }

Di chuyển từ 0.3.x

Bắt đầu từ 0.4.0, next-devtools-mcp là một trình kết nối mỏng.

Đã thay đổi:

• nextjs_docs không còn tải tài liệu qua mạng. Nó hướng tác nhân đến tài liệu mà Next.js đóng gói tại node_modules/next/dist/docs/ (hoặc khuyến nghị nâng cấp). Tài nguyên nextjs-docs://llms-index đã bị xóa.

Đã xóa:

• Công cụ init — nó chỉ thực thi quy trình tải tài liệu cũ.
• Các công cụ upgrade_nextjs_16 và enable_cache_components cùng lời nhắc của chúng — hiện được phân phối dưới dạng kỹ năng tác nhân.
• Tất cả tài nguyên cache-components://, nextjs16:// và nextjs-fundamentals:// — được thay thế bởi tài liệu đóng gói.

Những gì còn lại: nextjs_index, nextjs_call, nextjs_docs và browser_eval.

Quyền riêng tư & Đo lường từ xa

next-devtools-mcp thu thập dữ liệu đo lường từ xa ẩn danh để cải thiện công cụ:

• Sử dụng công cụ — công cụ MCP nào được gọi (ví dụ: nextjs_index, nextjs_call)
• Sự kiện lỗi — thông báo lỗi ẩn danh khi công cụ thất bại
• Siêu dữ liệu phiên — ID phiên, dấu thời gian, môi trường cơ bản (HĐH, phiên bản Node.js)

Không thu thập: mã của bạn, nội dung hoặc đường dẫn tệp, dữ liệu cá nhân, thông tin xác thực hoặc đối số công cụ (chỉ tên công cụ).

Các tệp cục bộ nằm trong ~/.next-devtools-mcp/ (telemetry-id ẩn danh, telemetry-salt và nhật ký gỡ lỗi mcp.log).

Từ chối bằng cách đặt biến môi trường (thêm vào ~/.zshrc / ~/.bashrc để duy trì):

export NEXT_TELEMETRY_DISABLED=1

Xóa dữ liệu đo lường từ xa cục bộ bất cứ lúc nào:

rm -rf ~/.next-devtools-mcp

Khắc phục sự cố

ERR_MODULE_NOT_FOUND tham chiếu đến next-devtools-mcp/dist — xóa bộ nhớ cache npx của bạn và khởi động lại máy khách MCP. Máy chủ sẽ cài đặt mới.

[error] No server info found — nextjs_index / nextjs_call cần máy chủ phát triển Next.js 16+ đang chạy:

1. Khởi động nó: npm run dev
2. Xác nhận Next.js 16+ (điểm cuối /_next/mcp chỉ tồn tại ở đó)
3. Xác minh nó khởi động không có lỗi

browser_eval và nextjs_docs hoạt động mà không cần máy chủ phát triển.

Phát triển cục bộ

git clone https://github.com/vercel/next-devtools-mcp.git
cd next-devtools-mcp
pnpm install
pnpm build

Trỏ máy khách MCP của bạn đến bản dựng cục bộ:

{
  "mcpServers": {
    "next-devtools": {
      "command": "node",
      "args": ["/absolute/path/to/next-devtools-mcp/dist/index.js"]
    }
  }
}

Hoặc với Codex:

codex mcp add next-devtools-local -- node dist/index.js

Xem tài liệu Next.js MCP để biết cách MCP hoạt động với Next.js và các tác nhân lập trình.

Giấy phép

MIT