@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

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

1.0.0 - 2025-01-07

Added

• Initial release of MCP server for Next.js development process management
• Four core MCP tools:
  • nextjs_dev_start - Start Next.js development server asynchronously
  • nextjs_get_logs - Retrieve filtered development logs with level, content, and time filtering
  • nextjs_get_status - Check server status, uptime, and process information
  • nextjs_stop_server - Stop development server gracefully or forcefully
• Real-time log collection and filtering from Next.js processes
• Circular buffer log storage (max 1000 entries) with automatic rotation
• Process lifecycle management with proper cleanup and signal handling
• TypeScript support with strict type checking and ES2022/ESM modules
• CLI interface with debug mode and help documentation
• Official MCP SDK integration with StdioServerTransport
• Zod schema validation for all tool parameters
• Comprehensive error handling with structured JSON responses
• MIT license and professional documentation

Features

• Non-blocking execution: Start Next.js dev servers without hanging Claude Code
• Smart port detection: Automatically extract port numbers from script commands
• Log level detection: Automatic categorization of logs as error, warn, or info
• Filtering capabilities: Filter logs by level, content, time, and line count
• Process monitoring: Track server uptime, PID, and status
• Graceful shutdown: Proper cleanup of processes and resources
• Debug mode: Comprehensive logging for troubleshooting
• Cross-platform: Works on Linux, macOS, and Windows with Node.js 22+

Technical Specifications

• Node.js 22+ required for latest ESM and performance features
• TypeScript 5.x with strict mode and full type safety
• Official @modelcontextprotocol/sdk for MCP protocol compliance
• Zod for runtime type validation and schema enforcement
• ESM modules with proper import/export handling
• Singleton pattern for state and process management
• Event-driven architecture for log collection and process monitoring

Documentation

• Comprehensive README with installation and usage instructions
• Claude Code integration guide with configuration examples
• Troubleshooting section with common issues and solutions
• API documentation for all MCP tools
• Development setup and building instructions
• Professional GitHub repository structure