@ld338/nextjs-mcp-server

A Model Context Protocol (MCP) server for managing Next.js development servers with comprehensive error monitoring. This tool allows you to start, stop, restart, and monitor multiple Next.js dev servers programmatically or via MCP-compatible clients (e.g., Claude, Copilot, or custom tools).

---

🚀 Features

• Server Management: Start, stop, restart Next.js development servers in any directory
• Overview: List all running servers with status, uptime, and performance metrics
• Port Management: Automatic port detection and conflict resolution
• Log Monitoring: Real-time logs and error tracking for all managed servers
• Turbo Support: Full support for Next.js Turbo mode
• Intelligent Error Handling: Detailed error messages for invalid projects, port conflicts, etc.
• Cross-Platform: Works on Windows, macOS, and Linux

---

📦 Installation

Global Installation (Recommended)

# With npm
npm install -g @ld338/nextjs-mcp-server

# With yarn
yarn global add @ld338/nextjs-mcp-server

# With pnpm
pnpm add -g @ld338/nextjs-mcp-server

Local Installation

npm install @ld338/nextjs-mcp-server

---

⚙️ Configuration

Claude Desktop Configuration

Add the following configuration to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "nextjs-manager": {
      "command": "nextjs-mcp-server",
      "args": []
    }
  }
}

GitHub Copilot Configuration

{
  "mcp": {
    "servers": {
      "nextjs-manager": {
        "command": "nextjs-mcp-server"
      }
    }
  }
}

---

🔧 Usage

Standalone

nextjs-mcp-server

The server communicates via MCP over stdio and is intended to be used as a backend for tools that support the Model Context Protocol.

With Claude

After configuration, you can use direct commands in Claude like:

• "Start a Next.js server in the current directory"
• "List all running Next.js servers"
• "Show logs from the server on port 3000"
• "Stop all Next.js servers"

---

🛠️ Available MCP Tools

Tool	Description	Parameters
nextjs_start	Start a Next.js dev server	directory, port?, turbo?
nextjs_stop	Stop a running server	port or pid
nextjs_restart	Restart a server	port or directory
nextjs_list	List all running servers	-
nextjs_status	Check status and port conflicts	port?
nextjs_logs	Get recent logs from a server	port, lines?

Example Usage

// Examples for tool usage
const tools = [
  {
    name: "nextjs_start",
    arguments: {
      directory: "/path/to/my-app",
      port: 3000,
      turbo: true,
    },
  },
  {
    name: "nextjs_logs",
    arguments: {
      port: 3000,
      lines: 50,
    },
  },
];

---

🏗️ Development

Setup

git clone https://github.com/ld338/nextjs-mcp-server.git
cd nextjs-mcp-server
npm install

Build

npm run build

Development Mode

npm run dev

Testing

npm test

Linting

npm run lint

---

📋 System Requirements

• Node.js: 18.0.0 or higher
• Next.js: 12.0.0 or higher (in managed projects)
• Operating System: Windows 10+, macOS 10.15+, Linux (Ubuntu 18.04+)

---

🐛 Troubleshooting

Common Issues

Server won't start:

# Check if port is already in use
netstat -an | grep :3000

# Check Next.js installation
npx next --version

MCP connection failed:

• Ensure configuration is correct
• Check paths to executable file
• Restart Claude/Copilot after configuration changes

Logs not available:

• Server must have been started via this tool
• Check file permissions in project directory

---

🤝 Contributing

Contributions are welcome! Please read the Contributing Guidelines before submitting pull requests.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

📄 Changelog

See CHANGELOG.md for details about changes between versions.

---

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: me@ld338.de

---

📜 License

This project is licensed under the MIT License.

---

👨‍💻 Author

Leo (@ld338)
📧 me@ld338.de

---

🙏 Acknowledgments

• Model Context Protocol team for the excellent protocol
• Next.js team for the fantastic framework
• All contributors and users of this tool

---

Persistente Server-Status & externe Analyse

Laufende Next.js-Server werden automatisch in der Datei ~/.nextjs-mcp-servers.json gespeichert. Diese Datei enthält für jeden gestarteten Server Informationen wie Port, PID, Verzeichnis und Startzeit. Beim Start des MCP-Servers werden diese Einträge geladen und auf laufende Prozesse geprüft. Beim Stoppen oder Beenden eines Servers wird die Datei aktualisiert.

Vorteile:

• Auch nach einem Neustart oder von anderen Tools (z.B. VSCode, Claude) können laufende Server erkannt werden.
• Tools können gezielt Logs holen oder Fehler analysieren, indem sie die Datei auslesen und z.B. per MCP-Tool nextjs_logs die Logs anfordern.
• Verwaiste Prozesse werden erkannt und automatisch aus der Datei entfernt.

Beispiel für externe Analyse:

1. Tool liest ~/.nextjs-mcp-servers.json und findet laufende Server (z.B. Port, Verzeichnis).
2. Tool sendet einen MCP-Request wie { name: "nextjs_logs", arguments: { directory: "/pfad/zum/projekt" } }.
3. Die Logs werden zurückgegeben und können analysiert werden.

Hinweis:

• Nur Server, die über dieses Tool gestartet wurden, werden automatisch mit Logs und Status verwaltet.
• Die Datei wird beim Start und Stoppen automatisch gepflegt.

---

Persistent Server State & External Analysis

Running Next.js servers are automatically tracked in the file ~/.nextjs-mcp-servers.json. This file contains information for each started server, such as port, PID, directory, and start time. On startup, the MCP server loads these entries and checks if the processes are still running. When a server is stopped or terminated, the file is updated accordingly.

Benefits:

• Even after a restart or from other tools (e.g. VSCode, Claude), running servers can be detected.
• Tools can fetch logs or analyze errors by reading this file and, for example, sending an MCP tool request like nextjs_logs to retrieve logs for a specific server.
• Stale or orphaned processes are detected and automatically removed from the file.

Example for external analysis:

1. A tool reads ~/.nextjs-mcp-servers.json and finds running servers (e.g. port, directory).
2. The tool sends an MCP request such as { name: "nextjs_logs", arguments: { directory: "/path/to/project" } }.
3. The logs are returned and can be analyzed.

Note:

• Only servers started via this tool are automatically managed with logs and status.
• The file is updated automatically on start and stop.
• The feature works on Windows, macOS, and Linux. On Windows, the file is stored in the user's home directory (e.g. C:\Users\<username>\.nextjs-mcp-servers.json).

---