thedotmack/the-dev-server-mcp

🚀 the-dev-server MCP

Let Claude register, start, and inspect every dev server you run with PM2.

Why • Features • Quick Start • Usage • Testing • How It Works • Documentation • Contributing

A Model Context Protocol (MCP) server that owns PM2 process management for your dev environments—Claude can register processes, boot them, inspect logs, and keep configuration in sync.

🎯 Why This Exists

Running multiple dev servers across projects quickly gets messy:

• ❌ Configs live in random scripts and terminal history
• ❌ Each teammate manages PM2 differently (or not at all)
• ❌ Restart workflows are tribal knowledge
• ❌ Log files are scattered and forgotten
• ❌ Claude has to guess which process you care about

the-dev-server MCP solves this by letting Claude act as the PM2 control plane. Every dev server you care about is registered once, stored in versioned JSON, and controlled through the same MCP tools.

✨ Features

• 🧠 Managed Process Registry – Declare every dev service (script, cwd, args, env) once; the MCP persists it in .the-dev-server-state.json.
• ⚙️ PM2 Orchestration – Start, stop, restart, delete, and describe processes entirely through MCP tools.
• � Config Drift Control – Update registrations, apply config changes to PM2 instantly, and keep state in sync.
• � Unified Status View – get-managed-processes merges the stored registry with live PM2 status so Claude sees what should exist and what’s actually running.
• 📝 Log Streaming – Tail standard/out or error logs from any registered process without leaving the conversation.
• 🩺 Troubleshooting Prompt – diagnose-server walks Claude through a PM2-first debugging workflow.
• 💾 Disk Persistence – Registrations survive MCP restarts, so once a process is defined it’s available forever.
• 🔧 macOS & Linux Support – Built for Unix environments where PM2 is available (Windows support coming later).

🚀 Quick Start

Installation

# Clone or download this repository
cd the-dev-server-mcp

# Install dependencies
npm install

# Build the project
npm run build

Configuration

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "the-dev-server": {
      "command": "node",
      "args": ["/absolute/path/to/the-dev-server-mcp/build/index.js"]
    }
  }
}

Replace /absolute/path/to/ with the actual path to your installation.

Restart Claude Desktop

After updating the config, restart Claude Desktop to load the MCP server.

Add Project Instructions (Recommended)

For best results, add instructions to your projects:

# For Claude - copy to your project root
cp /path/to/the-dev-server-mcp/CLAUDE.md.example /your/project/CLAUDE.md

# For CLI tools (Cline, Cursor, etc.) - copy to your project root
cp /path/to/the-dev-server-mcp/.clinerules.example /your/project/.clinerules

This ensures Claude and other AI assistants consistently use the MCP for server questions.

🔔 Note: The MCP includes built-in instructions that Claude sees automatically. Project files reinforce "always manage servers through PM2" on a per-repo basis.

📖 Usage

Day-to-day Flow

1. Register every dev server once

Claude: register-managed-process

{
  "name": "next-app",
  "script": "npm",
  "args": ["run", "dev"],
  "cwd": "/Users/alexnewman/Projects/next-app",
  "env": { "PORT": "3000" }
}

This stores the config locally and (optionally) starts it immediately through PM2.

2. Start / stop / restart on demand

• start-managed-process → boots the registered script via PM2
• stop-managed-process → graceful shutdown
• restart-managed-process → great for config reloads or code changes

3. Inspect state at any time

• get-managed-processes shows both the registry and live PM2 info side-by-side.
• describe-managed-process provides the raw PM2 describe output when you need low-level details.

4. Update definitions safely

• Use update-managed-process to change script args, env vars, interpreter, or watch/autorestart flags.
• Pass "applyToPm2": true to delete + re-register the PM2 process automatically.

5. Clean up when projects end

• delete-managed-process removes entries from both the registry and PM2 (unless you opt to keep the PM2 process running).

6. Tail logs directly in chat

• read-managed-process-logs supports type: "all" | "out" | "error" with configurable line counts.

7. Need the big picture?

• get-pm2-status always remains available for ad-hoc PM2 inspection across all processes (registered or not).

💡 Tip: The diagnose-server prompt orchestrates these steps automatically when the user says “the server is broken.”

Tool Reference

Resource

server-config – quick read-only access to the project’s package.json metadata.

Prompt

diagnose-server – structured PM2-first debugging checklist.

🧪 Testing with Examples

This repository includes two example applications to showcase the MCP in action:

Example Applications

1. Next.js App (examples/example-nextjs) - Next.js 15 + React 19 + TypeScript + Tailwind
2. Vite React App (examples/example-vite-react) - Vite + React 19 + TypeScript + Tailwind

Both apps include:

• A home page
• A nicely formatted documentation page
• Strict CLAUDE.md instructions for the MCP
• Ready-to-run configurations

How to Test

1. Install dependencies in an example:

   cd examples/example-nextjs
   npm install
   

2. Set your MCP-compatible AI assistant's project root to the example folder (e.g., examples/example-nextjs)

3. Use this exact prompt:

   Make the site 'pretty in pink' and make sure it builds and runs
   

4. What should happen:

   • The AI reads CLAUDE.md and sees the strict MCP instructions
   • It checks server status with get-managed-processes()
   • It registers the server if not registered
   • It modifies the styles to be "pretty in pink"
   • It uses the MCP to build and run the server (NOT direct npm commands)
   • It confirms everything works

What This Demonstrates

• ✅ The AI assistant remembers to use the MCP for all dev server operations
• ✅ The strict CLAUDE.md instructions are front and center
• ✅ No direct npm run dev or npm run build commands are used
• ✅ The MCP manages the entire lifecycle: register → start → build → logs

Testing Both Examples

Try the same prompt with both apps to see how the MCP handles different frameworks:

• Next.js with App Router
• Vite with React Router

Both should behave consistently through the MCP interface.

🏗️ How It Works

The MCP persists a registry file in your repo root: .the-dev-server-state.json.

interface ManagedProcessConfig {
  name: string;
  script: string;
  cwd?: string;
  args?: string[];
  env?: Record<string, string>;
  interpreter?: string;
  instances?: number;
  watch?: boolean;
  autorestart?: boolean;
}

interface DevServerState {
  managedProcesses: Record<string, ManagedProcessConfig>;
  lastSynced?: Date;
}

On startup the MCP loads this file, hydrates the registry, and every modification (register/update/delete) writes back to disk with a fresh timestamp. PM2 commands are executed using the stored config so the MCP always knows how to recreate a process.

🔧 Development

Watch Mode

npm run watch

Build

npm run build

Testing Locally

# Run the built server directly
node build/index.js

The server communicates via stdio, so it's designed to be used through Claude Desktop or another MCP client.

📋 Requirements

• Node.js 18+ (for ES2022 support)
• macOS or Linux (uses Unix commands like lsof and ps)
• TypeScript 5.7+

Note: Windows is not currently supported due to Unix-specific commands.

🎓 Best Practices

1. Register Before Running – Ensure every dev service has an entry in the registry so Claude can manage it.
2. Let the MCP Start/Stop – Resist pm2 CLI muscle memory; trigger lifecycle actions through MCP tools so state stays consistent.
3. Update Configs via MCP – Use update-managed-process instead of editing .the-dev-server-state.json by hand.
4. Lean on Diagnose Prompt – When a server misbehaves, the prompt orchestrates status, restart, and log inspection automatically.
5. Keep PM2 Clean – Use delete-managed-process when cleaning house to avoid orphaned processes.

📚 Documentation

🛣️ Roadmap

• Windows support (PowerShell PM2 parity)
• Multi-server orchestration (groups & dependency graphs)
• Docker/Compose target support in addition to PM2
• Health monitoring and automatic restart policies
• Remote environment support (SSH tunnels / containers)
• Rich history of restarts and log bookmarks

🤝 Contributing

Contributions are welcome! This is a utility MCP designed to solve a real pain point in Claude development workflows.

Ideas for contributions:

• Windows support implementation
• First-class Docker/Compose runners
• Process grouping and aggregate commands
• Watch-mode dashboards for PM2 metrics
• Documentation & onboarding improvements

📄 License

MIT

🙏 Acknowledgments

Built with:

• @modelcontextprotocol/sdk – Official TypeScript MCP SDK
• zod – Schema validation

💡 Related Projects

• MCP Servers - Official MCP server implementations
• Claude Desktop - Desktop app with MCP support

📮 Support

If you find this useful and it saves you time, consider:

• ⭐ Starring this repo
• 🐛 Reporting bugs via GitHub Issues
• 💡 Suggesting features
• 🔀 Contributing code

Never lose track of your dev server again. 🚀