npm-run-mcp-server

Give your AI Agent the power to build, test, and deploy your project using your existing package.json scripts.

npm-run-mcp-server is a Model Context Protocol (MCP) server that automatically bridges your project's npm scripts to your AI assistant.

🔍 Auto-detects your project's package.json (no hardcoded paths).
📦 Works with everything: npm, pnpm, yarn, and bun.
🔒 Safe & Configurable: Whitelist specific scripts to prevent accidental execution.
⚡ Zero-config: Works out of the box, but scales with detailed config.

⚡ Quick Start

Connect your agent to your scripts in seconds. No global installation required—just let npx handle it.

Claude Desktop

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "npm-scripts": {
      "command": "npx",
      "args": ["-y", "npm-run-mcp-server"]
    }
  }
}

Cursor

Go to Settings > Features > MCP Servers.
Click + Add New MCP Server.
Enter the details:
- Type: command
- Name: npm-scripts
- Command: npx
- Args: -y npm-run-mcp-server

VS Code (GitHub Copilot)

Add this to your workspace .vscode/settings.json:

{
  "github.copilot.chat.mcpServers": {
    "npm-scripts": {
      "command": "npx",
      "args": ["-y", "npm-run-mcp-server"]
    }
  }
}

🛠️ Configuration

While npm-run-mcp-server works instantly, you might not want your AI to have access to every script (like eject or publish). You can control this by creating an npm-run-mcp.config.json file in your project root.

Example Config

Create npm-run-mcp.config.json next to your package.json:

{
  "include": ["test", "lint", "build", "start"],
  "scripts": {
    "test": {
      "description": "Run the test suite. Use --watch for interactive mode.",
      "inputSchema": {
        "properties": {
          "watch": { "type": "boolean", "description": "Watch files for changes" }
        }
      }
    }
  }
}

Configuration Options

Field	Type	Description
`include`	`string[]`	Whitelist of script names to expose. If omitted, all scripts are exposed.
`exclude`	`string[]`	Blacklist of script names to hide.
`scripts`	`object`	Detailed configuration for specific scripts.

Per-Script Options

Inside the scripts object, you can map a script name to:

toolName: Override the tool name seen by the AI (e.g., rename test:unit to run_unit_tests).
description: Provide a custom description to help the AI understand when to use this script.
inputSchema: Define strictly typed arguments that the AI can pass (mapped to CLI flags).

📖 How It Works

Auto-Detection: When the server starts, it looks for a package.json in your current workspace. It supports standard formatting as well as npm, pnpm, yarn, and bun conventions.
Tool Creation: It converts your scripts into MCP Tools.
- Scripts like test:unit become tools like test_unit.
- The tool description includes the actual command (e.g., vitest run) so the AI knows what it's running.
Execution: When the AI calls a tool, the server executes the script in your project's root directory using the detected package manager.

🔧 Advanced / CLI Usage

You can run the server manually for debugging or if you need to pass specific flags.

# Run directly
npx npm-run-mcp-server --list-scripts

# Run in a specific directory
npx npm-run-mcp-server --cwd /path/to/project

# Force a specific package manager
npx npm-run-mcp-server --pm pnpm

CLI Flags

--cwd <path>: Manually set the working directory.
--pm <npm|pnpm|yarn|bun>: Force a specific package manager.
--config <path>: Path to a specific JSON config file.
--verbose: Print debug logs to stderr.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repo.
Create your feature branch (git checkout -b feature/amazing-feature).
Commit your changes (git commit -m 'Add some amazing feature').
Push to the branch (git push origin feature/amazing-feature).
Open a Pull Request.

License

MIT © fstubner