next-devtools-mcp-skill

# Next.js DevTools MCP Skill > Skill by [ara.so](https://ara.so) — Devtools Skills collection. Expert skill for using `next-devtools-mcp`, a Model Context Protocol (MCP) server that provides Next.js development tools and utilities for AI coding agents. Provides runtime diagnostics, documentation search, browser automation, and development workflow automation for Next.js projects. ## What is next-devtools-mcp? `next-devtools-mcp` is an MCP server that gives AI coding agents powerful Next.js development capabilities: - **Runtime Diagnostics** (Next.js 16+): Query running Next.js applications for errors, routes, logs, and real-time state - **Documentation Search**: Access official Next.js docs and knowledge base directly in conversations - **Browser Automation**: Test and verify Next.js pages with Playwright integration - **Development Workflows**: Automated upgrade guides and feature enablement prompts ## Installation ### Quick Install (Recommended) Install for all detected AI coding agents in your project: ```bash npx add-mcp next-devtools-mcp@latest ``` Add `-y` to skip confirmation. Add `-g` for global installation across all projects. ### Manual Installation Add to your MCP client configuration file: ```json { "mcpServers": { "next-devtools": { "command": "npx", "args": ["-y", "next-devtools-mcp@latest"] } } } ``` ### Agent-Specific Configuration **Claude Code / Claude Desktop:** ```bash claude mcp add next-devtools npx next-devtools-mcp@latest ``` **Cursor:** Click: [Install in Cursor](https://cursor.com/en/install-mcp?name=next-devtools&config=eyJjb21tYW5kIjoibnB4IC15IG5leHQtZGV2dG9vbHMtbWNwQGxhdGVzdCJ9) Or manually: `Cursor Settings` → `MCP` → `New MCP Server` **Codex:** ```bash codex mcp add next-devtools -- npx next-devtools-mcp@latest ``` For Windows 11, update `.codex/config.toml`: ```toml env = { SystemRoot="C:\\Windows", PROGRAMFILES="C:\\Program Files" } startup_timeout_ms = 20_000 ``` **VS Code / Copilot:** ```bash code --add-mcp '{"name":"next-devtools","command":"npx","args":["-y","next-devtools-mcp@latest"]}' ``` ## Requirements - Node.js v20.19+ (latest maintenance LTS) - npm or pnpm - For runtime diagnostics: Next.js 16+ dev server running ## Core Workflow ### 1. Always Initialize First **CRITICAL:** Call the `init` tool at the start of every Next.js session: ``` Use the init tool to set up Next.js DevTools context ``` This establishes proper documentation requirements and context. For automation, add to your agent's configuration: **`.claude/CLAUDE.md` or `.cursorrules`:** ```markdown 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. ``` ### 2. Start Next.js Dev Server (for Runtime Diagnostics) For Next.js 16+ projects: ```bash npm run dev # or pnpm dev ``` MCP is enabled by default at `http://localhost:3000/_next/mcp`. The `next-devtools-mcp` server auto-discovers and connects. ## MCP Tools Reference ### init Initialize Next.js DevTools MCP context. **Call this first in every session.** ```typescript // Tool input schema { project_path?: string // Optional, defaults to current directory } ``` **Example prompts:** - "Use the init tool to set up Next.js DevTools context" - "Initialize Next.js DevTools for this project" **What it does:** - Sets up AI assistant context for Next.js development - Establishes documentation-first approach (use `nextjs_docs` for all queries) - Documents all available tools and workflows - Provides best practices checklist ### nextjs_docs Search and retrieve official Next.js documentation. ```typescript // 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" } ``` **Example workflow:** ``` Search Next.js docs for generateMetadata ``` Agent uses: 1. `nextjs_docs` with `action: "search"`, `query: "generateMetadata"` 2. Reviews search results (titles, paths, snippets) 3. `nextjs_docs` with `action: "get"`, `path: "/docs/app/api-reference/functions/generate-metadata"` 4. Provides answer based on official documentation **Common searches:** - "Search Next.js docs for metadata generation" - "Find Next.js documentation on generateStaticParams" - "Look up middleware configuration in Next.js docs" - "Search App Router caching documentation" ### nextjs_index Query available runtime diagnostic resources from Next.js 16+ dev server. ```typescript // No input required {} ``` **Example prompts:** - "What runtime diagnostics are available?" - "Show me what I can query from the dev server" - "List available Next.js MCP resources" **Output:** List of available resource URIs (errors, routes, logs, etc.) ### nextjs_call Call a specific runtime diagnostic resource from Next.js 16+ dev server. ```typescript { uri: string // Resource URI from nextjs_index } ``` **Example workflows:** **Check for errors:** ``` Next Devtools, what errors are in my Next.js application? ``` Agent calls: `nextjs_call` with `uri: "nextjs://errors"` **View route structure:** ``` Next Devtools, show me the structure of my routes ``` Agent calls: `nextjs_call` with `uri: "nextjs://routes"` **Check dev server logs:** ``` Next Devtools, what's in the development server logs? ``` Agent calls: `nextjs_call` with `uri: "nextjs://logs"` **Common URIs:** - `nextjs://errors` - Runtime errors and warnings - `nextjs://routes` - App Router route structure - `nextjs://logs` - Development server logs - `nextjs://config` - Next.js configuration - `nextjs://env` - Environment variables ### browser_eval Automate browser testing with Playwright. Use for verifying pages, testing interactions, and detecting runtime issues. ```typescript // 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" } ``` **Example workflow - Test Next.js page:** ``` Test the homepage at localhost:3000 and take a screenshot ``` Agent executes: ```typescript // 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" } ``` **Common patterns:** **Verify upgrade (Next.js 15 → 16):** ``` Verify that my app works on localhost:3000 after the upgrade ``` **Test navigation:** ``` Test navigating from home to /about page ``` **Check for hydration errors:** ``` Load the page and check for React hydration errors in the console ``` **Important:** For Next.js 16+, prefer `nextjs_index` and `nextjs_call` over `browser_eval` console messages for error detection. ## Pre-Configured Prompts ### upgrade-nextjs-16 Guide for upgrading from Next.js 15 to Next.js 16. ``` Help me upgrade my Next.js app to version 16 ``` **What it does:** 1. Analyzes current project setup 2. Updates dependencies in `package.json` 3. Applies codemods for breaking changes 4. Updates configuration files 5. Tests the upgrade with browser verification ### enable-cache-components Enable Cache Components mode in Next.js 16. ``` Enable Cache Components in my Next.js app ``` **What it does:** 1. Adds `cache: "components"` to `next.config.ts` 2. Migrates components to use `"use cache"` directive 3. Updates data fetching patterns 4. Provides examples and documentation ## Knowledge Base Resources The MCP server includes focused documentation resources automatically available to agents: **Cache Components** (12 sections): - `cache-components://overview` - `cache-components://core-mechanics` - `cache-components://public-caches` - `cache-components://private-caches` - `cache-components://runtime-prefetching` - `cache-components://request-apis` - `cache-components://cache-invalidation` - `cache-components://advanced-patterns` - `cache-components://build-behavior` - `cache-components://error-patterns` - `cache-components://test-patterns` - `cache-components://reference` **Migration Guides:** - `nextjs16://migration/beta-to-stable` - `nextjs16://migration/examples` **Fundamentals:** - `nextjs-fundamentals://use-client` Resources are loaded on-demand by the agent as needed. ## Real-World Examples ### Example 1: Debug Runtime Error **User request:** ``` My Next.js app shows a blank page. Help me figure out what's wrong. ``` **Agent workflow:** ```typescript // 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 ``` ### Example 2: Upgrade to Next.js 16 with Cache Components **User request:** ``` Upgrade my app to Next.js 16 and enable Cache Components ``` **Agent workflow:** ```typescript // 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" }) ``` ### Example 3: Implement Metadata Generation **User request:** ``` Add proper SEO metadata to my blog post page