How to Use a Next.js MCP Server with Claude Code

Direct answer: In a Next.js 16+ project, add a root .mcp.json that runs next-devtools-mcp, start the Next.js development server, then restart Claude Code so it loads the connector. The connector discovers your local server and proxies the built-in /_next/mcp endpoint. You can then ask Claude Code for live errors, logs, routes, project metadata, and Server Action details.

What you are connecting

The official integration is a thin connector, not a second application server. next-devtools-mcp finds one or more running Next.js 16+ development servers and forwards MCP requests to each server’s built-in endpoint. Your app stays responsible for rendering and runtime behavior; Claude Code gets a standard MCP interface for development inspection.

Piece	Role
Next.js 16+ dev server	Runs the app and exposes `/_next/mcp`.
`next-devtools-mcp`	Discovers running dev servers and proxies MCP calls.
`.mcp.json`	Project-scoped Claude Code configuration.
Claude Code	MCP host that calls the discovered tools.

Prerequisites

Next.js 16 or newer.
Node.js and your project’s package manager.
Claude Code installed and opened in the project directory.
A development command such as pnpm dev, npm run dev, yarn dev, or bun dev.

The integration is for a running development server and does not require special hardware.

Set up the official Next.js MCP server

Check your Next.js version. Run next --version or inspect package.json. Upgrade to Next.js 16+ if needed.
Create .mcp.json at the project root. Put it beside package.json.

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

Start the app.

# choose the command your project uses
pnpm dev
# npm run dev
# yarn dev
# bun dev

Restart when configuration changes. If the dev server was already running when you created or edited .mcp.json, stop and start it again. Restart Claude Code or reload its MCP configuration so the project file is read.
Ask Claude Code for a discovery check. Request project metadata or current errors. A successful response proves the connector found the dev server.

See the Next.js documentation for version-specific guidance.

What Claude Code can inspect

get_errors: current build, runtime, and type errors.
get_logs: development-server logs.
get_page_metadata: routes and component/rendering metadata.
get_project_metadata: project structure and detected dev-server URL.
get_server_action_by_id: lookup of a Server Action by identifier.

The official guide also describes a Next.js knowledge base, migration helpers, Cache Components guidance, and browser testing through Playwright integration.

Use a reliable diagnostic sequence

Ask for get_project_metadata and confirm the project path and dev-server URL.
Ask for get_errors and fix build, runtime, or type failures first.
Ask for get_logs while reproducing the issue in a browser.
Ask for get_page_metadata for a route that renders incorrectly.
Use get_server_action_by_id when a form or mutation reports an opaque Action ID.

This ordering separates discovery failures from application failures.

Build your own application MCP server

The official devtools connector is for diagnostics. If you want Claude Code to call domain operations such as “find an order” or “create a preview,” expose a separate MCP endpoint in your Next.js App Router application. The Vercel Labs mcp-for-next.js template uses mcp-handler with the MCP TypeScript SDK and serves an endpoint such as http://localhost:3000/mcp. Its deployment notes require Node.js 20 or later for Vercel deployment.

Choose the right server

Question	Official connector	Custom app server
Purpose	Inspect errors, logs, routes, metadata, and Server Actions.	Expose domain tools, resources, or prompts.
Endpoint	`/_next/mcp`.	An App Router route such as `/mcp`.
Where it runs	Local development.	Local or deployed, with transport and auth decisions.
API surface	Next.js diagnostics and guidance.	Domain tools, resources, prompts, and optional browser automation.

Minimal route shape

Start from the template rather than guessing SDK wiring. Add tools, prompts, and resources in app/mcp/route.ts, run the app, and verify /mcp. The MCP TypeScript SDK defines the server primitives; Claude Code is a compatible MCP host.

// app/mcp/route.ts
// 1. Create the MCP server with the current TypeScript SDK.
// 2. Register tools, resources, and prompts.
// 3. Export App Router handlers for the supported transport.

Do not configure the custom /mcp route as a replacement for the devtools connector unless you need application tools. They solve different problems and can run as separate MCP servers.

Claude-side configuration and security

Claude Code can connect to multiple MCP servers. For remote servers, Anthropic’s MCP documentation covers server URLs, tool allowlists and denylists, OAuth bearer-token authentication, and multiple-server connections. CLI flags and beta headers are release-sensitive, so check the documentation for your installed Claude Code and Anthropic versions.

Keep local development servers bound to expected interfaces.
For a deployed /mcp endpoint, require authentication supported by your transport and host.
Allowlist only the tools Claude needs.
Treat mutating tools as production capabilities and separate environments.

Common errors and fixes

Symptom	Likely cause	Fix
Claude reports no Next.js server	The dev server is stopped, uses Next.js older than 16, or is unreachable.	Confirm the version, run the dev command, and verify the local URL.
Configuration is ignored	`.mcp.json` is not at the root or Claude has not reloaded it.	Move it beside `package.json`; restart Claude Code and the dev server.
`npx` fails	Node/npm is unavailable, the network cannot fetch the package, or the command was edited.	Check `node --version`, test the documented command, and restore it if needed.
Tools connect but show app errors	The MCP path works; your build, runtime, or types are failing.	Call `get_errors`, then inspect `get_logs`.
Wrong project is inspected	Multiple dev servers are running or Claude opened from another directory.	Close unrelated servers, open Claude at the intended root, and confirm project metadata.
Changes are not visible	Stale dev process or cached module state.	Restart the dev server and reload Claude’s MCP configuration.
Custom `/mcp` route returns 404	The route file is misplaced or the server was not restarted.	Place it at `app/mcp/route.ts`, confirm the template export shape, and restart.
Remote custom server is rejected	Transport, URL, or authentication does not match current host requirements.	Check current Claude and Anthropic MCP documentation and verify auth settings.

Performance, reliability, and cost

Startup: npx may resolve the connector on first use. Pin a tested version when reproducibility matters.
Discovery: A stopped or sleeping dev process cannot answer. A metadata call is a useful health check.
Signal quality: Query focused tools before broad explanations to reduce repeated log transfer.
Cost: The local connector and Next.js dev server do not add a per-request MCP service charge. A deployed custom server has the compute, network, and model-host costs of your platform.
Version drift: Next.js, the connector, MCP SDK, Claude Code, and transports change independently. Pin versions and recheck documentation during upgrades.

Or skip the browser setup

If your goal is simply to obtain a clean screenshot or PDF for an agent workflow, ScreenshotNeo provides a one-call API and an MCP server. It removes cookie banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, timeouts, failed loads, and cache hits are not billed. Responses identify page verdict and billing status with X-Page-Verdict and X-Billed headers. Claude, Cursor, and other MCP clients can use take_screenshot, get_page_info, and capture_pdf.

See the ScreenshotNeo API documentation for all options.

cURL

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Python

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)

Node.js

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

Every feature is available on every plan: full-page and element capture, device presets or custom viewports, dark mode, retina scale, PDF options, custom CSS and JavaScript, click and wait actions, request blocking, headers/cookies/user agent, timezone and geolocation, transparent backgrounds, resizing, configurable caching, signed links, async webhooks, bulk capture, usage reporting, and an OpenAPI spec. 1,000 screenshots per month are free with no card; paid plans start at $5 for 3,000.

Start with 1,000 free screenshots a month.

FAQ

Does this work with a production Next.js deployment?

The official devtools connector is designed around a running Next.js development server. For production or shared environments, build and secure a custom MCP route.

Can one Claude Code session use multiple Next.js projects?

The connector can discover one or more running Next.js development servers. Use project metadata to verify which server is being queried.

Do I need to expose my app publicly?

No for local development. Public exposure becomes a deployment and authentication concern only for a remote custom MCP server.

Is an MCP server the same as a browser automation server?

No. MCP standardizes tools, resources, and prompts. Browser testing can be added through Playwright integration.

Where should I look when a custom server breaks after an upgrade?

Check the current Next.js MCP guide, the template README, the MCP TypeScript SDK documentation, and current Claude Code or Anthropic MCP documentation.