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 interface
Pass script arguments: Provide optional command-line arguments to scripts via an args parameter
Automatic detection: Dynamically finds the closest package.json and 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-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.
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.
Connect your agent to your scripts in seconds. No global installation required—just let npx handle it.
Add this to your claude_desktop_config.json:
{
"mcpServers": {
"npm-scripts": {
"command": "npx",
"args": ["-y", "npm-run-mcp-server"]
}
}
}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
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
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.
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" }
}
}
}
}
}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. |
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).
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.
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--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.
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.
MIT © Felix Stubner
Run npm script "build": node scripts/build.cjs
| Name | Required | Description | Default |
|---|---|---|---|
| _ | No | ||
| args | No | Optional arguments appended after -- to the script |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only repeats the command, omitting details like side effects (e.g., file modifications), failure modes, or idempotency. The minimal information ('node scripts/build.cjs') fails to convey the tool's impact beyond execution.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that directly states the tool's action and underlying command. It has no wasted words and is front-loaded with the key information. Every part earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and lack of output schema, the description should still cover prerequisites, consequences (e.g., builds project), and error handling. It only states the command, leaving the agent uninformed about the tool's full role in the build process.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% (only 'args' has a description). The tool description does not explain the '_' parameter (array of strings appended to the script) or elaborate on 'args' usage. It adds no meaning beyond the existing schema description, failing to compensate for the low coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the action ('Run npm script') and the target resource ('build'), specifying the exact command 'node scripts/build.cjs'. It clearly distinguishes from sibling tools (prepublishonly, start, test, test_integration) by referencing the specific npm script name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus siblings, nor any prerequisites, alternatives, or when not to use it. The description is purely functional without contextual usage instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run npm script "prepublishOnly": npm run build
| Name | Required | Description | Default |
|---|---|---|---|
| _ | No | ||
| args | No | Optional arguments appended after -- to the script |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only states it runs the script, but does not disclose potential side effects, permission requirements, or error behavior. For a script runner, more detail on process and outcomes is needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that directly states the action. It is appropriately sized and front-loaded with the key information. No unnecessary text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is very minimal. It does not explain the npm lifecycle context (prepublishOnly runs before publish) or how it differs from a plain build. With no output schema and sibling tools, it should provide more context for agent decision-making.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% (args has description, _ does not). The tool description does not add any parameter-specific meaning beyond what is already in the schema for 'args'. No additional clarity on parameters is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool runs the npm script 'prepublishOnly' which executes 'npm run build'. It identifies the specific script, but lacks distinction from the sibling 'build' tool, which might run build directly. Still, it is specific enough for basic understanding.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives like 'build' or 'test'. It does not mention that it is typically executed before publishing or that it is part of the npm lifecycle. The description only states what it does, not when to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run npm script "start": node ./dist/index.js
| Name | Required | Description | Default |
|---|---|---|---|
| _ | No | ||
| args | No | Optional arguments appended after -- to the script |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Does not disclose side effects, permissions, or potential destructive actions. Annotations absent, so description should cover behavior but only states the command.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise, single sentence. Could be improved with structure but is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Missing details about return value, error handling, or execution context. For a simple script runner, it's borderline adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is low (50%), and description does not explain the '_' parameter. Only provides minimal info for 'args'. Fails to compensate for missing schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool runs the npm start script, specifying the exact command. Distinguishes from siblings by naming the specific script.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like build or test. No context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run npm script "test": node dist/index.js --list-scripts && node scripts/integration-test.mjs && echo 'MCP server test completed successfully'
| Name | Required | Description | Default |
|---|---|---|---|
| _ | No | ||
| args | No | Optional arguments appended after -- to the script |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It does reveal the exact commands run and the expected success message, but does not disclose any side effects (e.g., whether tests modify data or make network requests).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently conveys the command to run. It is concise but could be more structured by separating the explanation of the tool from the literal command.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with no output schema and two parameters. The description covers the basic behavior (running the npm test script) but omits any explanation of what the test does or what the expected output is beyond the success message.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%. The description adds meaning for 'args' by stating it is appended after '--', but the '_' parameter has no description in either the schema or the description. The description partially compensates for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool runs the npm 'test' script and provides the exact command executed. However, it does not distinguish this from the sibling tool 'test_integration', which likely has overlapping functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus the siblings 'build', 'start', or 'test_integration'. The description lacks any context about appropriate use cases or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run npm script "test:integration": node scripts/integration-test.mjs
| Name | Required | Description | Default |
|---|---|---|---|
| _ | No | ||
| args | No | Optional arguments appended after -- to the script |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It only says 'Run npm script', but does not disclose any behavioral traits such as side effects, prerequisites, or failure modes. This is insufficient for an agent to understand the tool's impact.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that effectively conveys the core action. It is front-loaded and free of extraneous information, though slightly more detail could be added without harming conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of output schema and the simple parameters, the description is minimal. It fails to explain expected outputs or results of running the script, leaving the agent with incomplete context for a test tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%; the 'args' parameter has a description, but the '_' parameter lacks one. The tool description adds no additional meaning beyond the schema, and it does not compensate for the missing schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool runs the npm script 'test:integration' and specifies the command. However, it does not differentiate from the sibling 'test' tool, although the tool name implies a specific integration test.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus siblings like 'test' or 'build'. The description only states what it does, leaving the agent without context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
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…
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/fstubner/npm-run-mcp-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
