npx add-mcp next-devtools-mcp@latest

{
  "mcpServers": {
    "next-devtools": {
      "command": "npx",
      "args": ["-y", "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

code --add-mcp '{"name":"next-devtools","command":"npx","args":["-y","next-devtools-mcp@latest"]}'

Use the init tool to set up Next.js DevTools context

When starting work on a Next.js project, ALWAYS call the `init` tool from
next-devtools-mcp FIRST to set up proper context and establish documentation
requirements. Do this automatically without being asked.

npm run dev

MCP is enabled by default at `http://localhost:3000/_next/mcp`. The `next-devtools-mcp` server auto-discovers and connects.

// Tool input schema
{
  project_path?: string  // Optional, defaults to current directory
}

// Search for docs
{
  action: "search",
  query: string,           // e.g., "metadata", "generateStaticParams"
  routerType?: "app" | "pages" | "all"  // default: "all"
}

// Get full doc content
{
  action: "get",
  path: string,            // e.g., "/docs/app/api-reference/functions/refresh"
  anchor?: string          // e.g., "usage"
}

Search Next.js docs for generateMetadata

// No input required
{}

{
  uri: string  // Resource URI from nextjs_index
}

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?

// Start browser
{
  action: "start",
  browser?: "chrome" | "firefox" | "webkit" | "msedge",  // default: "chrome"
  headless?: boolean  // default: true
}

// Navigate to URL
{
  action: "navigate",
  url: string
}

// Click element
{
  action: "click",
  selector: string  // CSS selector
}

// Type text
{
  action: "type",
  selector: string,
  text: string
}

// Fill form
{
  action: "fill_form",
  fields: Array<{ selector: string; value: string }>
}

// Execute JavaScript
{
  action: "evaluate",
  script: string
}

// Take screenshot
{
  action: "screenshot",
  path?: string  // default: auto-generated
}

// Get console messages
{
  action: "console_messages"
}

// Close browser
{
  action: "close"
}

Test the homepage at localhost:3000 and take a screenshot

// 1. Start browser
{ action: "start", headless: true }

// 2. Navigate
{ action: "navigate", url: "http://localhost:3000" }

// 3. Wait for content
{ action: "evaluate", script: "document.querySelector('h1')?.textContent" }

// 4. Screenshot
{ action: "screenshot" }

// 5. Check for errors
{ action: "console_messages" }

// 6. Clean up
{ action: "close" }

Verify that my app works on localhost:3000 after the upgrade

Test navigating from home to /about page

Load the page and check for React hydration errors in the console

Help me upgrade my Next.js app to version 16

Enable Cache Components in my Next.js app

My Next.js app shows a blank page. Help me figure out what's wrong.

// 1. Initialize (if not done)
init({ project_path: "." })

// 2. Check runtime errors
nextjs_call({ uri: "nextjs://errors" })

// Output shows: "ReferenceError: window is not defined at Component.render"

// 3. Search docs for server component issues
nextjs_docs({ 
  action: "search", 
  query: "window is not defined server component" 
})

// 4. Get full doc content
nextjs_docs({ 
  action: "get", 
  path: "/docs/app/building-your-application/rendering/server-components"
})

// 5. Provide solution: Add "use client" directive

Upgrade my app to Next.js 16 and enable Cache Components

// 1. Initialize
init({ project_path: "." })

// 2. Use upgrade prompt
// Triggers: upgrade-nextjs-16 prompt
// - Updates package.json
// - Runs codemods
// - Updates config

// 3. Enable Cache Components
// Triggers: enable-cache-components prompt
// - Adds cache: "components" to next.config.ts
// - Shows migration examples

// 4. Verify with browser
browser_eval({ action: "start" })
browser_eval({ action: "navigate", url: "http://localhost:3000" })
browser_eval({ action: "console_messages" })
browser_eval({ action: "screenshot" })
browser_eval({ action: "close" })

// 5. Check runtime state
nextjs_call({ uri: "nextjs://errors" })

Add proper SEO metadata to my blog post page

// 1. Search docs
nextjs_docs({ 
  action: "search", 
  query: "generateMetadata" 
})

// 2. Get detailed docs
nextjs_docs({ 
  action: "get", 
  path: "/docs/app/api-reference/functions/generate-metadata" 
})

// 3. Implement based on docs

// app/blog/[slug]/page.tsx
import { Metadata } from 'next'

interface Props {
  params: { slug: string }
}

export async function generateMetadata({ params }: Props): Promise<Metadata> {
  const post = await fetch(`${process.env.API_URL}/posts/${params.slug}`)
    .then(res => res.json())
  
  return {
    title: post.title,
    description: post.excerpt,
    openGraph: {
      title: post.title,
      description: post.excerpt,
      images: [{ url: post.image }],
    },
  }
}

export default async function BlogPost({ params }: Props) {
  const post = await fetch(`${process.env.API_URL}/posts/${params.slug}`)
    .then(res => res.json())
  
  return (
    <article>
      <h1>{post.title}</h1>
      <div dangerouslySetInnerHTML={{ __html: post.content }} />
    </article>
  )
}

Convert my data fetching component to use Cache Components

// app/posts/page.tsx
export const revalidate = 3600

export default async function PostsPage() {
  const posts = await fetch('https://api.example.com/posts')
    .then(res => res.json())
  
  return (
    <div>
      {posts.map(post => (
        <article key={post.id}>
          <h2>{post.title}</h2>
        </article>
      ))}
    </div>
  )
}

nextjs_docs({ 
  action: "search", 
  query: "use cache directive" 
})

// Then gets resource
// (agent has cache-components://core-mechanics available)

// app/posts/page.tsx
import { Posts } from './Posts'

export default function PostsPage() {
  return <Posts />
}

// app/posts/Posts.tsx
"use cache"
export const revalidate = 3600

export async function Posts() {
  const posts = await fetch('https://api.example.com/posts')
    .then(res => res.json())
  
  return (
    <div>
      {posts.map(post => (
        <article key={post.id}>
          <h2>{post.title}</h2>
        </article>
      ))}
    </div>
  )
}

import type { NextConfig } from 'next'

const config: NextConfig = {
  experimental: {
    cache: 'components',  // Enable Cache Components
  },
}

export default config

undefined

Access in code:
```typescript
const apiUrl = process.env.API_URL
const secret = process.env.NEXTAUTH_SECRET

http://localhost:{PORT}/_next/mcp

// Search first
nextjs_docs({ action: "search", query: "feature-name" })

// Get detailed docs
nextjs_docs({ action: "get", path: "/docs/..." })

// Then implement based on official documentation

// ✅ Preferred
nextjs_call({ uri: "nextjs://errors" })

// ❌ Avoid when above is available
browser_eval({ action: "console_messages" })

// At start of every Next.js session
init({ project_path: "." })

// Step 1: Search to find relevant docs
nextjs_docs({ action: "search", query: "..." })

// Step 2: Get full content from search results
nextjs_docs({ action: "get", path: "..." })

// 1. Check runtime errors
nextjs_call({ uri: "nextjs://errors" })

// 2. Visual verification
browser_eval({ action: "start" })
browser_eval({ action: "navigate", url: "http://localhost:3000" })
browser_eval({ action: "screenshot" })
browser_eval({ action: "close" })

// 3. Check routes structure
nextjs_call({ uri: "nextjs://routes" })