npm-run-mcp-server

An MCP server that exposes package.json scripts as tools for agents.

typescript

3

GitHub Stars

typescript

Language

6 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "fstubner-npm-run-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "npm-run-mcp-server"
      ]
    }
  }
}

This MCP server automatically bridges your project's npm scripts to your AI assistant. It auto-detects your package.json, supports multiple package managers, and lets you selectively expose scripts for safe, streamlined AI-driven build, test, and deployment workflows.

How to use

Connect your AI client to the server to enable access to your npm scripts. The server automatically discovers scripts, converts them into MCP tools, and executes them in your project’s root directory using the detected package manager. You can tailor which scripts are exposed and describe how each should be used, so your AI can run builds, tests, and other tasks safely and predictably.

How to install

Prerequisites: Node.js installed on your machine, and access to your project directory that contains package.json.

Install and run the MCP server via npx. You do not need a global installation.

# Quick start: run the MCP server directly with npx
npx npm-run-mcp-server

Advanced usage and configuration

You can fine-tune which npm scripts are exposed to the AI and provide additional details for each script. This helps prevent accidental execution of sensitive scripts and clarifies how each script behaves.

Configuration can be placed in a file named npm-run-mcp.config.json at your project root. The config controls which scripts are whitelisted, and allows per-script overrides for descriptions and input schemas.

Security and best practices

Whitelist only the scripts you want the AI to access. Use descriptive tool descriptions to guide when and how to invoke each script. Keep sensitive operations restricted behind explicit allowlists.

Available tools

npm_script

Executes a named npm script from your package.json, converting the script into an MCP tool for AI usage.