next-devtools-mcp: a thin MCP proxy for a running Next.js 16 dev server
Next.js Development for Coding Agent
At a glance
- What is it?
- The package does not inspect your app itself. It discovers Next.js 16+ dev servers, proxies their built-in MCP endpoint at /_next/mcp, and hands two other jobs (docs, browser work) back to the agent.
- Who is it for?
- Adopt it if you run Next.js 16 or newer and want an agent to read real build errors, routes and dev logs from a server you already have running; skip it if you are on Next.js 15 or older, or if you want a server that queries your app on its own. Before trusting it, start npm run dev, call nextjs_index to confirm the port and PID it reports, then call nextjs_call with toolName get_errors and check the returned JSON against what your terminal shows.
- Can I use it commercially?
- Not without permission. GitHub finds no licence file in the repository, and without a licence all rights are reserved by default: you may read the code but not reuse it. Check the README, or ask the authors, before using it.
- Is it still maintained?
- Yes. The repository last received commits 1 day ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap it fills: agents that cannot see the running app
A coding agent editing a Next.js project works from files. It reads components, routes and config, and it guesses at what the browser and the dev server are doing. When a build fails or a route throws at runtime, the agent usually learns about it only if you paste the error back into the conversation. next-devtools-mcp exists to close that loop for Next.js 16 and newer, where the framework itself exposes a Model Context Protocol endpoint at /_next/mcp while the dev server runs. The package does not add instrumentation to your app and does not parse your source tree. It finds servers that are already running and forwards questions to them. The audience is narrow and specific: developers using MCP-capable agents such as Claude Code, Cursor, Codex, Amp, Gemini, VS Code Copilot or Warp on a Next.js 16+ project that is running locally. If your dev server is not up, the interesting half of the tool set has nothing to talk to.
Thin connector: discovery, proxying, and two gateways
The README calls the package a thin connector, and the tool table backs that up. Two tools do the proxying. nextjs_index takes no parameters, scans common ports for running Next.js 16+ dev servers, and returns JSON listing each server's port, PID and URL together with the runtime tools that server exposes. nextjs_call then invokes one of those runtime tools, taking port and toolName as required inputs and an optional args object. The example given is {"port": 3000, "toolName": "get_errors"}. The runtime tools themselves belong to Next.js, not to this package, and the README notes they vary by version: get_errors for build, runtime and type errors, get_logs for the dev log file path, get_page_metadata for routes and component metadata, get_project_metadata for project structure and the dev server URL, and get_server_action_by_id to resolve a Server Action ID back to its source file. The remaining two tools are gateways rather than workers. nextjs_docs does not fetch documentation; it checks whether the installed Next.js release bundled markdown at node_modules/next/dist/docs/ and returns reading instructions for the agent. browser_eval points the agent at the agent-browser CLI instead of driving a browser through MCP. The stated reason is speed: the agent runs the CLI directly, which the README argues is faster than proxying every browser action through the protocol.
Install: one npx command, or a JSON block per client
The shortest path is add-mcp, which the README recommends for installing across all detected agents: npx add-mcp next-devtools-mcp@latest, with -y to skip the prompt and -g to install globally across projects. Manual configuration is a standard MCP server block with command npx and args ["-y", "next-devtools-mcp@latest"]. Client-specific commands are listed for several agents, including claude mcp add next-devtools npx next-devtools-mcp@latest, codex mcp add next-devtools -- npx next-devtools-mcp@latest, amp mcp add next-devtools -- npx next-devtools-mcp@latest, and code --add-mcp with an inline JSON string for VS Code. Gemini has both a project form and a user-scoped form using -s user. On Windows 11 with Codex, the README asks for environment variables and a longer startup timeout in .codex/config.toml: env = { SystemRoot="C:\\Windows", PROGRAMFILES="C:\\Program Files" } and startup_timeout_ms = 20_000. The requirements are Node.js v20.19 or a newer LTS release, npm or pnpm, and Next.js 16+ with a running dev server for the discovery and call tools. Pinning @latest means your client tracks new releases without you editing config, which cuts both ways: you also inherit any breaking change to the tool surface.
What 0.3.x users lose, and why the server got smaller
The README is explicit that docs and migration workflows no longer live in this server. Next.js now bundles its own documentation at node_modules/next/dist/docs/, and upgrade and Cache Components workflows ship as agent skills rather than as MCP tools. There is a dedicated migration section for 0.3.x users, which tells you the tool names and behaviour changed between the 0.3 line and 0.4.0. Anyone with prompts or agent instructions written against 0.3.x tools should expect to rewrite them, not just bump the version. The trade is coherent: documentation that ships inside the installed Next.js release cannot drift from the version you actually run, whereas a docs tool inside a separately versioned MCP server can. The cost is that the package now depends on Next.js having bundled those files. The README acknowledges the hole directly: if an installed release has no bundled docs, including early 16.x releases, nextjs_docs falls back to https://nextjs.org/docs and asks the agent to verify APIs against the installed version. That fallback is weaker than a version-matched local file, and the README does not claim otherwise.
The 60-second deadline and other constraints you inherit
The documentation states that upstream requests, including response-body reads, have a 60-second deadline. For get_errors, get_logs or get_page_metadata on a healthy dev server that is generous. For a tool that triggers compilation, or a Server Action lookup on a large project, it is a ceiling you did not choose and cannot raise from the MCP client config shown in the README. The README also says that cancelling an MCP request aborts its upstream network work, and that discovery releases response bodies used only to detect the protocol, which suggests the author thought about resource cleanup rather than leaving sockets open. The harder constraint is the version floor. Next.js 16+ with a running dev server is a requirement for nextjs_index and nextjs_call, so on Next.js 15 or older the two tools that do the actual work are unavailable and you are left with the docs gateway and the browser gateway, neither of which inspects your app. Port scanning is another assumption worth naming: discovery scans common ports, so a dev server bound to an unusual port, or one behind a proxy or container network boundary, may simply not appear in the index output.
Where it sits next to a full MCP server
The obvious comparison is a general-purpose MCP server that exposes its own tools for filesystem access, shell execution or browser control, and answers from its own implementation. next-devtools-mcp takes the opposite position: it owns almost no behaviour. Errors, routes, logs and Server Action resolution are produced by Next.js at /_next/mcp, and the package's job is to find that endpoint and forward the call. That difference has practical consequences. A self-contained server keeps working when the framework changes, because the server author absorbs the change. A proxy keeps working only while the upstream contract holds, and the README's note that runtime tools vary by Next.js version is exactly that risk surfacing. In exchange, a proxy cannot report stale state: what comes back is what the running server currently says, with no cache layer in between. For browser work the package goes further and refuses to proxy at all, deferring to the agent-browser CLI. If your agent already has a capable browser tool, browser_eval adds little. If it does not, the README's position is that installing the CLI beats routing every action through MCP.
Maintenance, versioning and the licence question
The release history supplied here shows v0.4.0 in June 2026, preceded by v0.3.10 in January 2026 and v0.3.8 earlier that month, with the default branch last pushed in September 2026. That is a project still moving through 0.x, and the 0.3.x to 0.4.0 migration section confirms the tool surface is not frozen. Practically, that means two upgrade costs. The first is client configuration: @latest keeps you current automatically, so a breaking change arrives without a deliberate decision on your side, and pinning a version trades that away for manual bumps. The second is agent instructions: any prompt that names a tool from the 0.3.x era needs editing. On licensing, the repository metadata supplied for this review does not state a licence, and the README does not mention one either. Treat the licence as unverified until you read the LICENSE file in the repository yourself; nothing here should be read as legal advice about redistribution or commercial use. The package is published on npm as next-devtools-mcp, so the published tarball's metadata is the other place to confirm it.
Editorial conclusion
Adopt it if you run Next.js 16 or newer and want an agent to read real build errors, routes and dev logs from a server you already have running; skip it if you are on Next.js 15 or older, or if you want a server that queries your app on its own. Before trusting it, start npm run dev, call nextjs_index to confirm the port and PID it reports, then call nextjs_call with toolName get_errors and check the returned JSON against what your terminal shows.
Community notes