npm-run

npm-run-mcp-server automatically bridges your project's npm scripts to your AI assistant. It auto-detects your package.json and exposes scripts from npm, pnpm, yarn, or bun workflows as MCP Tools, allowing the AI to suggest and execute commands like test, build, start, lint, or any custom script you whitelist. You can control which scripts are exposed by adding an npm-run-mcp.config.json at the project root, enabling safer automation by restricting access to sensitive tasks (e.g., eject or publish). The server runs via npx by default, ensuring a zero-config setup while still supporting detailed configuration for advanced use cases.

To use it, simply run the MCP server through your preferred client (e.g., Claude Desktop, Cursor, or VS Code) using the provided npx command. The tools generated from your scripts will include the actual underlying command so the AI understands what will be executed (for example, npm run test or pnpm test). When invoked by the AI, the server executes the script in your project root with the detected package manager, preserving your project’s local environment. You can also customize tool names, descriptions, and argument schemas for individual scripts via the npm-run-mcp.config.json file.

Prerequisites:

• Node.js and npm (or pnpm/yarn/bun as alternative package managers) installed on your machine.
• Access to the internet to fetch the MCP server package via npx.

Install and run:

1. Install and run the MCP server on demand using npx (no global install required):

# Quick start (no global install required)
npx -y npm-run-mcp-server

2. If you want to explicitly run a server instance for a project, ensure you are in the project root (where package.json is located) and start as above:

npx -y npm-run-mcp-server

3. Optional: Install via package managers for local development or CI:

npm install --save-dev npm-run-mcp-server

4. If you plan to customize configuration, add an npm-run-mcp.config.json in the project root to whitelist scripts and provide per-script options as described in the README.

Tips and common issues:

• Auto-detection works with standard package.json formats and supports npm, pnpm, yarn, and bun as package managers.
• Use npm-run-mcp.config.json to whitelist exposed scripts and tailor tool descriptions or input schemas for the AI.
• When using in environments with restricted network access, ensure npx can fetch npm-run-mcp-server or use a local installation.
• The quick start examples show how to integrate with Claude Desktop, Cursor, and VS Code by configuring the MCP server via their respective config payloads.
• If you encounter permission or path issues, run the command with appropriate working directory using the --cwd flag of the MCP server CLI (when supported by your setup).
• The server exposes scripts as MCP Tools; names and descriptions can be customized per-script in the configuration to improve AI selection and clarity.