This MCP server enables AI agents to execute npm package.json scripts as tools, providing seamless integration with development workflows.
Core Capabilities:
Execute npm scripts: Run any script defined in your project's
package.json(e.g.,build,start,test,prepublishOnly) through an AI interfacePass script arguments: Provide optional command-line arguments to scripts via an
argsparameterAutomatic detection: Dynamically finds the closest
package.jsonand detects your package manager (npm, pnpm, yarn, or bun)Multi-project support: Works across different projects without configuration changes by automatically targeting the current project context
AI Integration:
Compatible with GitHub Copilot Chat, Claude Code (VS Code and desktop), and Cursor
Functions as a Model Context Protocol (MCP) server for AI-assisted development
Additional Features:
CLI functionality to list available scripts and run with verbose output
Override automatic detection with custom working directory and package manager options
Detailed logging for debugging purposes
Exposes package.json scripts as MCP tools, allowing AI agents to execute Bun scripts with optional arguments
Exposes package.json scripts as MCP tools, allowing AI agents to execute npm scripts with optional arguments
Exposes package.json scripts as MCP tools, allowing AI agents to execute pnpm scripts with optional arguments
Exposes package.json scripts as MCP tools, allowing AI agents to execute Yarn scripts with optional arguments
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@npm-run-mcp-serverrun the test suite with watch mode enabled"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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:
Cursor
Go to Settings > Features > MCP Servers.
Click + Add New MCP Server.
Enter the details:
Type:
commandName:
npm-scriptsCommand:
npxArgs:
-y npm-run-mcp-server
VS Code (GitHub Copilot)
Add this to your workspace .vscode/settings.json:
Related MCP server: SuperiorAPIs MCP Server Tool
🛠️ 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:
Configuration Options
Field | Type | Description |
|
| Whitelist of script names to expose. If omitted, all scripts are exposed. |
|
| Blacklist of script names to hide. |
|
| 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., renametest:unittorun_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.jsonin your current workspace. It supports standard formatting as well asnpm,pnpm,yarn, andbunconventions.Tool Creation: It converts your scripts into MCP Tools.
Scripts like
test:unitbecome tools liketest_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.
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