Npm Run MCP Server

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

1. Go to Settings > Features > MCP Servers.
2. Click + Add New MCP Server.
3. 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

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

1. 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.
2. 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.

1. 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 : Manually set the working directory.
• --pm : Force a specific package manager.
• --config : 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.

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

License

MIT © Felix Stubner