npm-run-mcp-server
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 "Deploy 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-server run 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:
{
"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:
commandName:
npm-scriptsCommand:
npxArgs:
-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"]
}
}
}Related MCP server: mcp-makefile-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 |
|
| 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.
# 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 pnpmCLI 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 © Felix Stubner
Available Tools
5 toolsbuildB
Run npm script "build": node scripts/build.cjs
Inputs: _, args.
prepublishonlyC
Run npm script "prepublishOnly": npm run build
Inputs: _, args.
startB
Run npm script "start": node ./dist/index.js
Inputs: _, args.
testB
Run npm script "test": node dist/index.js --list-scripts && node scripts/integration-test.mjs && echo 'MCP server test completed successfully'
Inputs: _, args.
test_integrationC
Run npm script "test:integration": node scripts/integration-test.mjs
Inputs: _, args.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool corresponds to a distinct npm script (build, prepublishOnly, start, test, test:integration) with no overlap in purpose or description.
Tool names are mostly lowercase but mix single words (build, start, test) and compound names with varying conventions (prepublishonly as one word, test_integration with underscore). A more consistent pattern like 'prepublish_only' would improve clarity.
5 tools is ideal for a focused server designed to run specific npm scripts. Each tool serves a clear purpose without unnecessary clutter.
The server covers the typical lifecycle scripts (build, start, test) and includes integration testing. It may lack common scripts like lint or format, but is sufficient for the stated domain of running predefined npm scripts.
Maintenance
Related MCP Connectors
MCP connector that lets ChatGPT list, search, and run your Apple Shortcuts via a local Mac agent
Package intelligence MCP for AI agents — 22 tools, 19 ecosystems, AGPL SDK, free.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables AI assistants to manage development workflows by running build commands, executing tests, analyzing package.json files, installing dependencies, and performing code linting. Supports multiple package managers (npm, yarn, pnpm) and provides detailed error reporting for development operations.5MIT
- AlicenseBqualityDmaintenanceExposes Makefile targets as MCP tools, allowing AI agents to execute project automation tasks like build, test, and deploy through natural language.121MIT
- AlicenseNot gradedqualityBmaintenanceAutomatically generates MCP tools, CLI, and web UI from TypeScript methods, enabling AI agents and chat clients to interact with custom capabilities defined once.252 npm100MIT
- AlicenseNot gradedqualityAmaintenanceProvides MCP servers that wrap common developer tools (git, npm, docker, etc.) returning structured JSON output, enabling AI agents to reliably interact with these tools without parsing fragile terminal text.141MIT