主题
Next.js MCP 服务器
¥Next.js MCP Server
模型上下文协议 (MCP) 是一个开放标准，允许 AI 代理和编码助手通过标准化接口与你的应用交互。
¥The Model Context Protocol (MCP) is an open standard that allows AI agents and coding assistants to interact with your applications through a standardized interface.
Next.js 16+ 包含 MCP 支持，使编码代理能够实时访问应用的内部结构。要使用此功能，请安装 next-devtools-mcp 包。
¥Next.js 16+ includes MCP support that enables coding agents to access your application's internals in real-time. To use this functionality, install the next-devtools-mcp package.
入门
¥Getting started
要求：Next.js 16 或更高版本
¥Requirements: Next.js 16 or above
将 next-devtools-mcp 添加到项目根目录下的 .mcp.json 文件中：
¥Add next-devtools-mcp to the .mcp.json file at the root of your project:
完成！当你启动开发服务器时，next-devtools-mcp 会自动发现并连接到正在运行的 Next.js 实例。
¥That's it! When you start your development server, next-devtools-mcp will automatically discover and connect to your running Next.js instance.
更多配置选项，请参阅 next-devtools-mcp 仓库。
¥For more configuration options, see the next-devtools-mcp repository.
功能
¥Capabilities
next-devtools-mcp 为编码代理提供了一系列不断增长的功能：
¥next-devtools-mcp provides coding agents with a growing set of capabilities:
应用运行时访问
¥Application Runtime Access
错误检测：从开发服务器检索当前构建错误、运行时错误和类型错误
¥Error Detection: Retrieve current build errors, runtime errors, and type errors from your dev server
实时状态查询：访问实时应用状态和运行时信息
¥Live State Queries: Access real-time application state and runtime information
页面元数据：查询页面路由、组件和渲染详情
¥Page Metadata: Query page routes, components, and rendering details
服务器操作：检查服务器操作和组件层级结构
¥Server Actions: Inspect Server Actions and component hierarchies
开发日志：访问开发服务器日志和控制台输出
¥Development Logs: Access development server logs and console output
开发工具
¥Development Tools
Next.js 知识库：查阅全面的 Next.js 文档和最佳实践
¥Next.js Knowledge Base: Query comprehensive Next.js documentation and best practices
迁移和升级工具：使用代码转换自动升级到 Next.js 16 的辅助工具
¥Migration and Upgrade Tools: Automated helpers for upgrading to Next.js 16 with codemods
缓存组件指南：缓存组件的设置和配置帮助
¥Cache Components Guide: Setup and configuration assistance for Cache Components
浏览器测试：Playwright MCP 集成用于在浏览器中验证页面
¥Browser Testing: Playwright MCP integration for verifying pages in the browser
注意：Next.js 团队正在积极扩展这些功能。我们会定期添加新工具和功能，以改善代理开发体验。
¥Note: The Next.js team is actively expanding these capabilities. New tools and features are added regularly to improve the agent development experience.
开发工作流程
¥Development workflow
启动 Next.js 开发服务器：
¥Start your Next.js development server:
bash
npm run dev你的编码代理将通过
next-devtools-mcp自动连接到正在运行的 Next.js 实例¥Your Coding Agent will automatically connect to the running Next.js instance via
next-devtools-mcp在浏览器中打开你的应用以查看页面
¥Open your application in the browser to view pages
查询你的代理以获取洞察和诊断信息（请参见以下示例）
¥Query your agent for insights and diagnostics (see examples below)
可用工具
¥Available tools
通过 next-devtools-mcp，代理可以使用以下工具：
¥Through next-devtools-mcp, agents can use the following tools:
get_errors：从开发服务器检索当前构建错误、运行时错误和类型错误¥
get_errors: Retrieve current build errors, runtime errors, and type errors from your dev serverget_logs：获取包含浏览器控制台日志和服务器输出的开发日志文件的路径。¥
get_logs: Get the path to the development log file containing browser console logs and server outputget_page_metadata：获取特定页面的元数据，包括路由、组件和渲染信息¥
get_page_metadata: Get metadata about specific pages including routes, components, and rendering informationget_project_metadata：检索项目结构、配置和开发服务器 URL¥
get_project_metadata: Retrieve project structure, configuration, and dev server URLget_server_action_by_id：通过 ID 查找服务器操作，以找到源文件和函数名。¥
get_server_action_by_id: Look up Server Actions by their ID to find the source file and function name
与代理一起使用
¥Using with agents
兼容 MCP 的编码代理可以自动发现并连接到你的 Next.js 开发服务器，并为其提供有关你项目的丰富上下文信息。
¥MCP-compatible Coding Agents can automatically discover and connect to your Next.js development server, providing them with rich context about your project.
辅助代理开发的优势
¥Benefits for agent-assisted development
代理可以：
¥Agents can:
提供上下文感知建议：根据现有结构，推荐添加新功能的合适位置
¥Make context-aware suggestions: Recommend the right place to add new features based on your existing structure
查询实时应用状态：在开发过程中检查当前配置、路由和中间件。
¥Query live application state: Check current configuration, routes, and middleware during development
了解你的应用路由页面布局：准确了解渲染的页面和布局
¥Understand your app router pages layout: Know exactly which page and layout are rendered
提供精确的实现：生成符合项目模式和约定的代码
¥Provide accurate implementations: Generate code that follows your project's patterns and conventions
示例
¥Examples
错误检测和诊断
¥Error detection and diagnosis
实时查询代理的错误信息：
¥Ask your agent about errors in real-time:
bash
User: "What errors are currently in my application?"代理将：
¥The agent will:
通过
next-devtools-mcp查询你正在运行的 Next.js 应用¥Query your running Next.js application via
next-devtools-mcp检索当前构建错误、运行时错误和类型错误
¥Retrieve current build errors, runtime errors, and type errors
分析错误并提供可操作的修复方案
¥Analyze the errors and provide actionable fixes
Agent response (click to expand)
bash
> fix errors on the page
⏺ I'll help you fix the errors on the page. Let me first check what errors exist by looking at the
current state of the project.
⏺ next-devtools - nextjs_runtime (MCP)(action: "discover_servers")
⏺ next-devtools - nextjs_runtime (MCP)(action: "call_tool", toolName: "get_errors")
⏺ I found a hydration error on the /about page. The error shows that the server is rendering
"server" but the client is rendering "client", causing a mismatch. Let me create a todo list and fix
this issue.
⏺ Perfect! Now let me check for errors on the page. 01:14 PM claude-sonnet-4-5-20250929
⏺ next-devtools - nextjs_runtime (MCP)(action: "call_tool", toolName: "get_errors")
⎿ {
"success": true,
"port": 3000,
"toolName": "get_errors",
"result": {
"content": [
{
"type": "text",
"text": "# Found errors in 1 browser session(s)\n\n## Session: /about\n\n**1 error(s)
found**\n\n### Runtime Errors\n\n#### Error 1 (Type: recoverable)\n\n**Error**: Hydration failed升级及最佳实践
¥Upgrading and best practices
获取 Next.js 概念和迁移方面的帮助：
¥Get help with Next.js concepts and migrations:
bash
User: "Help me upgrade my Next.js app to version 16"代理将分析你当前的版本，指导你使用代码转换工具进行自动化迁移，并提供处理重大变更的分步说明。
¥The agent will analyze your current version, guide you through automated migrations with codemods, and provide step-by-step instructions for handling breaking changes.
提出概念性问题：
¥Ask conceptual questions:
bash
User: "When should I use 'use client' in App Router?"代理将查询 Next.js 知识库，并提供基于文档的解释以及来自你代码库的示例。
¥The agent will query the Next.js knowledge base and provide documentation-backed explanations with examples from your codebase.
怎么运行的
¥How it works
Next.js 16+ 包含一个内置的 MCP 端点 /_next/mcp，该端点在你的开发服务器中运行。next-devtools-mcp 包会自动发现并与这些端点通信，从而实现以下功能：
¥Next.js 16+ includes a built-in MCP endpoint at /_next/mcp that runs within your development server. The next-devtools-mcp package automatically discovers and communicates with these endpoints, allowing it to:
连接到运行在不同端口上的多个 Next.js 实例
¥Connect to multiple Next.js instances running on different ports
将工具调用转发到相应的 Next.js 开发服务器
¥Forward tool calls to the appropriate Next.js dev server
为编码代理提供统一的接口
¥Provide a unified interface for coding agents
这种架构将代理接口与内部实现解耦，使 next-devtools-mcp 能够在不同的 Next.js 项目中无缝运行。
¥This architecture decouples the agent interface from the internal implementation, enabling next-devtools-mcp to work seamlessly across different Next.js projects.
故障排除
¥Troubleshooting
MCP 服务器无法连接
¥MCP server not connecting
确保你使用的是 Next.js v16 或更高版本。
¥Ensure you're using Next.js v16 or above
验证
next-devtools-mcp是否已在你的.mcp.json中配置¥Verify
next-devtools-mcpis configured in your.mcp.json启动你的开发服务器：
npm run dev¥Start your development server:
npm run dev如果开发服务器已在运行，则重新启动它。
¥Restart your development server if it was already running
检查你的编码代理是否已加载 MCP 服务器配置。
¥Check that your coding agent has loaded the MCP server configuration