MCP Rewatch

🚀 MCP Rewatch

A Model Context Protocol (MCP) server that enables AI coding assistants like Claude Code to manage long-running development processes.

When using AI coding assistants such as Claude Code for development, there's a significant hurdle. Without MCP Rewatch, Claude Code can't execute commands like npm run dev effectively. It gets stuck waiting for the process to finish, eventually timing out without getting any output.

🚧 The Problem

While using Claude Code for development, you'll encounter a fundamental limitation:

# What happens when Claude Code tries to run a dev server:
$ npm run dev

> my-app@1.0.0 dev
> next dev

▲ Next.js 14.0.0
- Local: http://localhost:3000

[Claude Code is now stuck here, waiting for the process to exit]
[After ~2 minutes, it times out without seeing any output]
[Claude Code never sees compilation errors, success messages, or any logs]

Claude Code cannot:

• ❌ See any output from long-running processes
• ❌ Know if a dev server started successfully
• ❌ Check for compilation errors
• ❌ Restart servers after making changes
• ❌ Run multiple dev processes simultaneously

This situation makes it extremely difficult to develop effectively with Claude Code, as you have to manually run all dev servers and restart them after each change.

💡 The Solution

MCP Rewatch serves as a bridge between Claude Code and your development processes:

• Runs processes in the background - Ensures Claude Code doesn't block.
• Captures all output - Saves stdout/stderr in memory buffers.
• Provides async access - Allows Claude Code to check logs at any time.
• Enables restarts - Empowers Claude Code to restart servers after changes.
• Manages multiple processes - Facilitates running frontend, backend, and database servers concurrently.

🔍 How It Works

MCP Rewatch acts as an intermediary between Claude Code and your development processes:

1. Runs as a separate service that Claude Code can communicate with via MCP.
2. Manages processes independently - Starts your dev servers as child processes.
3. Non-blocking operations - Allows Claude Code to start/restart processes and continue immediately.
4. Async log retrieval - Enables Claude Code to check logs later without blocking.
5. Handles lifecycle properly - Ensures graceful shutdown and no orphaned processes.

This architecture enables Claude Code to effectively manage long-running processes despite its inherent limitation of not being able to run them directly.

📦 Installation

Install globally via npm:

npm install -g mcp-rewatch

Or use directly with npx (no installation needed):

npx mcp-rewatch

⚙️ Configuration

Create a rewatch.config.json file in your project root (where you'll be running Claude Code):

The startupDelay should be adjusted according to your specific processes:

• Fast tools (scripts, small servers): 1000 - 2000ms
• Next.js/React dev servers: 3000 - 5000ms
• Heavy build processes: 5000 - 10000ms
• Services with dependencies: 8000 - 15000ms

{
  "processes": {
    "convex": {
      "command": "pnpm",
      "args": ["dlx", "convex", "dev"],
      "cwd": "./",
      "startupDelay": 5000
    },
    "nextjs": {
      "command": "pnpm",
      "args": ["dev"],
      "cwd": "./",
      "env": {
        "PORT": "3000"
      },
      "startupDelay": 4000 
    },
    "backend": {
      "command": "npm",
      "args": ["run", "dev"],
      "cwd": "./backend",
      "env": {
        "NODE_ENV": "development",
        "PORT": "8080"
      },
      "startupDelay": 2000
    }
  }
}

Configuration Options

💻 Usage with Claude Code

🚀 Quick Start (Single Project)

1. Add MCP Rewatch to Claude Code:

# Using npx (no installation needed)
claude mcp add rewatch npx -- mcp-rewatch

# Or if installed globally
claude mcp add rewatch mcp-rewatch

# Or for local development
claude mcp add rewatch node -- /path/to/mcp-rewatch/dist/index.js

2. Create rewatch.config.json in your project root.

3. Start Claude Code from your project directory - MCP Rewatch will look for the config in the current working directory.

🌐 User-Scoped Setup (Global Access)

To make MCP Rewatch available in all Claude Code sessions:

claude mcp add -s user rewatch npx -- mcp-rewatch

⚠️ Important Note

The server looks for rewatch.config.json in the current working directory where Claude Code is running. Each project needs its own config file.

📂 Managing Multiple Projects

How it works: MCP Rewatch looks for rewatch.config.json in the current working directory where Claude Code is running.

Best practices:

1. Keep configs project-specific: Each project should have its own rewatch.config.json.
2. Use relative paths: In your config, use relative cwd paths like "./backend" or "./frontend".
3. Launch Claude Code from project root: Always start Claude Code from your project directory.

Example multi-service config:

{
  "processes": {
    "frontend": {
      "command": "npm",
      "args": ["run", "dev"],
      "cwd": "./frontend"
    },
    "backend": {
      "command": "npm",
      "args": ["run", "dev"],
      "cwd": "./backend"
    },
    "database": {
      "command": "docker",
      "args": ["compose", "up", "postgres"],
      "cwd": "./"
    }
  }
}

🛠️ Available Tools

Once configured, Claude Code can use these tools:

restart_process

Stop and restart a development process by name. Waits for the configured startupDelay (or 3 seconds by default), then returns initial logs.

await restart_process({ name: "nextjs" })
// Output:
// Process 'nextjs' started successfully
//
// Initial logs:
// [2024-01-07T10:00:01.123Z] [stdout] > my-app@1.0.0 dev
// [2024-01-07T10:00:01.456Z] [stdout] > next dev
// [2024-01-07T10:00:02.789Z] [stdout] ▲ Next.js 14.0.0
// [2024-01-07T10:00:03.012Z] [stdout] - Local: http://localhost:3000

get_process_logs

Retrieve logs from a process, optionally limiting the number of lines.

await get_process_logs({ name: "nextjs", lines: 50 })
// Returns last 50 lines of logs from the Next.js process

await get_process_logs({ name: "convex" })
// Returns all available logs from the Convex process

list_processes

List all configured processes and their current status.

await list_processes()
// Output:
// nextjs: running (PID: 12345)
// convex: stopped

stop_all

Stop all running processes gracefully.

await stop_all()
// Output: "All processes stopped"

⚙️ Typical Workflow

Here's how Claude Code uses MCP Rewatch during development:

1. Initial setup (done once by you):

   • Create rewatch.config.json in your project.
   • Start Claude Code - servers can be started on demand.

2. During development Claude Code will:

   • Make code changes to your files.
   • Call restart_process({ name: "nextjs" }) to restart the server.
   • Automatically receive initial logs after a 3 - second startup delay.
   • Check the logs for success indicators or errors.
   • Continue with more changes based on the results.
   • Call get_process_logs({ name: "nextjs" }) later if needed.

3. Key benefits:

   • Claude Code never gets blocked by long - running processes.
   • You don't need to manually restart servers after every change.
   • Claude Code can verify changes worked by checking logs.
   • Multiple servers can be managed in parallel.

How It Works

When restart_process is called:

1. Stops any existing process with that name.
2. Starts the new process.
3. Waits for the configured startupDelay (default: 3 seconds).
4. Returns the startup status and initial logs.

This gives Claude Code immediate feedback about whether:

• The process started successfully.
• There were immediate errors (port conflicts, missing deps).
• The server is beginning to compile/build.

For ongoing monitoring, Claude Code can use get_process_logs to check progress later.

🤔 Why This Matters

Without MCP Rewatch, the development flow with Claude Code is frustrating:

• ❌ Claude Code tries npm run dev → blocks and times out.
• ❌ You make changes → servers break → manual restart needed.
• ❌ No way to check if changes compiled successfully.

With MCP Rewatch:

• ✅ Claude Code uses restart_process → returns immediately.
• ✅ Servers restart automatically after changes.
• ✅ Claude Code can check logs to verify success.

🐞 Troubleshooting

⚠️ Important Note

• Processes not starting: Check that rewatch.config.json exists in your project root.
• Permission errors: Ensure the commands in your config have proper execution permissions.
• Can't find tools: Verify MCP Rewatch appears in Claude Code's MCP menu.
• Logs not appearing: Processes might be buffering output; some servers need specific flags to disable buffering.

🛠️ Development

To contribute to MCP Rewatch:

git clone https://github.com/brennancheung/mcp-rewatch.git
cd mcp-rewatch
pnpm install
pnpm build

For development, you can point Claude Code directly to the built output:

# Build the project
pnpm build

# Add to Claude Code
claude mcp add rewatch-dev node -- /path/to/mcp-rewatch/dist/index.js

Then create a rewatch.config.json in whatever directory you're testing from.