@ai-mapping/mcp-nextjs-dev

MCP server for managing Next.js development processes with Claude Code

An official Model Context Protocol (MCP) server that enables AI assistants like Claude Code to manage Next.js development servers without blocking. Start, monitor, and debug Next.js applications seamlessly through AI-powered development workflows.

Features

🚀 Non-blocking Next.js development server management
📊 Real-time log access and filtering
🛠️ Process monitoring and control
🔧 Debug-friendly with comprehensive error handling
🤖 Optimized for AI assistant integration

Problem Solved

Claude Code hangs when running npm run dev because the process doesn't terminate. This MCP server provides asynchronous tools to start Next.js development servers in the background and access their logs for analysis.

Installation

Prerequisites

• Node.js 22+
• Next.js project

Quick Start

# Install and run
npx @ai-mapping/mcp-nextjs-dev

# Or install globally
npm install -g @ai-mapping/mcp-nextjs-dev
mcp-nextjs-dev

Claude Code Integration

Add to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "nextjs-dev": {
      "command": "npx",
      "args": ["@ai-mapping/mcp-nextjs-dev"],
      "cwd": "."
    }
  }
}

Usage with Claude Code

Example Prompts

Start Development Server:

"Start the Next.js development server for this project"

Check for Errors:

"Are there any compilation errors in the Next.js logs? Show me the last 20 error messages."

Monitor Server Status:

"Is the Next.js development server still running? What's the current status?"

Debug Issues:

"The app isn't working. Can you check the Next.js logs for any warnings or errors in the last 2 minutes?"

Clean Shutdown:

"Stop the Next.js development server and clean up any processes."

Available Tools

• nextjs_dev_start - Start Next.js development server
• nextjs_get_logs - Retrieve filtered development logs
• nextjs_get_status - Check server status and uptime
• nextjs_stop_server - Stop development server gracefully

Configuration

Command Line Options

npx @ai-mapping/mcp-nextjs-dev --help
npx @ai-mapping/mcp-nextjs-dev --debug

Environment Variables

# Enable debug logging
DEBUG=1 npx @ai-mapping/mcp-nextjs-dev

Development

This project uses:

• TypeScript with ES modules
• Node.js 22+ features
• Official MCP SDK
• pnpm package manager

Building from Source

# Clone the repository
git clone https://github.com/ai-mapping/mcp-nextjs-dev.git
cd mcp-nextjs-dev

# Install dependencies
pnpm install

# Build the project
pnpm run build

# Run tests
pnpm test

Project Structure

@ai-mapping/mcp-nextjs-dev/
├── src/
│   ├── server.ts          # Main MCP server
│   ├── cli.ts            # CLI entry point
│   ├── managers/         # Process and state management
│   └── types/            # TypeScript definitions
├── dist/                 # Compiled JavaScript
└── bin/                  # Executable scripts

Troubleshooting

Common Issues

Port Already in Use:

# Check what's using the port
lsof -i :3000
# Kill the process
kill -9 <PID>

MCP Connection Issues:

# Test MCP server directly
npx @modelcontextprotocol/inspector npx @ai-mapping/mcp-nextjs-dev

Debug Mode:

# Enable detailed logging
DEBUG=1 npx @ai-mapping/mcp-nextjs-dev --debug

Getting Help

• 📚 MCP Documentation
• 🐛 Report Issues
• 💬 Discussions

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE file for details.

Links

• 🏠 Homepage
• 📦 NPM Package
• 🚀 AI Mapping Organization

Made with ❤️ by the AI Mapping team