ScreenshotNeo
Sign in Get a free key

BlogAI agents

How to Use the Next.js DevTools MCP Server

Configure Next.js DevTools MCP, connect an AI coding agent, inspect errors and metadata, and fix common connection problems.

By the ScreenshotNeo team1 October 20264 min read

Direct answer: Next.js DevTools MCP connects an MCP-compatible coding agent to a running Next.js 16+ development server. Add the server entry to .mcp.json at your project root, start the app, restart or reconnect your agent, then ask it for errors, logs, route metadata, project metadata, or Server Action details.

The official Next.js guide describes MCP as an open standard for letting AI agents and coding assistants interact with applications through a standard interface. The setup below follows that guide (updated February 27, 2026) and the Next.js 16 upgrade documentation.

Prerequisites

  • Next.js 16 or later.
  • An MCP-compatible coding agent or client.
  • Node.js and your project’s package manager.
  • A development server that the MCP package can discover.

Check your Next.js version:

npm list next
# or
pnpm list next
# or
yarn why next

1. Add the MCP server configuration

Create .mcp.json beside package.json:

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

-y lets npx install without a prompt. @latest follows the newest package, which helps updates but is not pinned for reproducible builds. Keep JSON strict: no comments or trailing commas, and never put secrets in this file.

2. Start the Next.js development server

Run the project’s normal development command from its root:

pnpm dev
# npm run dev
# or yarn dev

Leave it running. The MCP package is designed to discover the running development instance automatically. Open the app in a browser after it starts.

3. Connect your coding agent

  1. Open the project in your MCP-compatible agent.
  2. Allow it to load the root .mcp.json.
  3. Restart its MCP connection if it was already open.
  4. Open the app in a browser.

Ask focused questions such as “Show current build, runtime, and type errors” or “What routes and rendering modes does this app expose?”

What the documented tools can inspect

Tool Use
get_errors Current build, runtime, and type errors.
get_logs Path to development logs, including browser console and server output.
get_page_metadata Page routes, components, and rendering details.
get_project_metadata Project structure, configuration, and dev-server URL.
get_server_action_by_id Source file and function name for a Server Action ID.

The feature set is described as growing and may also include live state, component hierarchies, a Next.js documentation knowledge base, migration help, Cache Components guidance, and Playwright MCP browser testing. Recheck the current guide before relying on any particular tool.

Diagnostic workflow

  1. Run get_project_metadata to confirm the detected root and URL.
  2. Run get_errors for a baseline.
  3. Use get_page_metadata for the affected route.
  4. Use get_logs when browser or server output is needed.
  5. Use get_server_action_by_id for a Server Action ID.
  6. Make one focused change, reload, and request diagnostics again.

Configuration and security notes

  • Place .mcp.json at the project root.
  • Use a local or controlled development server; do not expose diagnostic logs publicly.
  • Keep credentials in your normal secret store, not prompts or config.
  • next-devtools-mcp@latest changes over time; pin a reviewed version when needed.
  • For multiple apps, open the agent in the intended app directory.

Why the server may not connect

Symptom Cause Fix
No tools appear Client did not load config. Validate root .mcp.json, then restart MCP.
No app discovered Dev server is stopped or another project is running. Run pnpm dev from the root and open the app.
Version error Next.js is older than 16. Upgrade to Next.js 16+, then restart server and agent.
Stale errors Old process or connection state. Restart the dev server and agent, reload, and retry.
npx install failure Changed command, blocked network, or package policy. Restore npx -y next-devtools-mcp@latest and check package access.
Incomplete metadata Route is not open or still compiling. Open the route, wait for compilation, and retry.

Performance and reliability

Results depend on a healthy, fully compiled development process. Keep the server running, avoid switching project directories during a session, and repeat queries after reloads. The first npx connection may include package resolution and download time; a pinned, cached version can make team startup more predictable.

Or skip the browser setup

For a rendered image or PDF instead of live-app inspection, ScreenshotNeo is a website screenshot API and MCP server. It removes cookie banners, consent prompts, newsletter popups, and chat widgets before capture. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers report the page verdict and billing status.

See the ScreenshotNeo API docs for all options:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

Its MCP server works with Claude, Cursor, and any MCP client. Other options include full-page or element capture, device presets, dark mode, custom CSS and JavaScript, waits, request blocking, headers and cookies, geolocation, PDFs, async jobs, bulk capture, caching, signed links, and a usage API. Every feature is on every plan. Free includes 1,000 screenshots/month with no card; paid plans start at $5 for 3,000.

Create a free ScreenshotNeo account and use the 1,000 monthly screenshots without a card.

FAQ

Does this work with Next.js 15?

The documented requirement is Next.js 16 or later.

Must I install the package globally?

No. The npx entry installs and runs it for the MCP client.

Is @latest reproducible?

No. Pin a reviewed version when deterministic builds matter.

Can it diagnose production?

The documented workflow targets a running Next.js development instance.

Keep reading