Next.js DevTools MCP

Next.js DevTools MCP

next-devtools-mcp là một máy chủ Giao thức Ngữ cảnh Mô hình (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.

Đây là một bộ 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à chuyển tiếp điểm cuối MCP tích hợp của chúng (/_next/mcp) để các tác nhân nhận được lỗi thời gian chạy, tuyến đường và nhật ký trực tiếp. Nó cũng cung cấp hai cổng kết nối hướng dẫn 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 của riêng mình tại node_modules/next/dist/docs/, và các quy trình nâng cấp / Thành phần Bộ nhớ đệm đượ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 bằng 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ầu 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 theo máy khách cụ thể

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+ bậ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 kết nối 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 chuyển tiếp 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 bộ 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 dẫn 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ả các tài nguyên cache-components://, nextjs16:// và nextjs-fundamentals:// — được thay thế bằng 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ụ gặp sự cố
• Siêu dữ liệu phiên — ID phiên, dấu thời gian, môi trường cơ bản (hệ điều hành, 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 dưới ~/.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

Xử lý sự cố

ERR_MODULE_NOT_FOUND tham chiếu 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ủ cài đặt lại mới.

[error] No server info found — nextjs_index / nextjs_call cần một 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 mà 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 MCP của Next.js để 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