npm-run-mcp-server

A Model Context Protocol (MCP) server that exposes your project's

Table of Contents

• Install

• Usage

  • As an MCP Server

  • As a CLI Tool

• Configuration

  • GitHub Copilot (VS Code)

  • Cursor

  • Claude Code

  • Multi-Project Workflow

  • Auto-Restart on Script Changes

  • Script Exposure Config

  • Install from source

• Testing with MCP Inspector

• CLI Options

• Contributing

  • Reporting Issues

  • Submitting Changes

  • Development Setup

• License

Related MCP server: SuperiorAPIs MCP Server Tool

Install

Installation options.

Usage

MCP server and CLI tool usage.

As an MCP Server

Add this server to your MCP host configuration. It uses stdio and automatically detects your project's package.json using workspace environment variables or by walking up from the current working directory.

Key Features:

• Automatic Workspace Detection: Works seamlessly across different projects without configuration changes

• Smart Tool Names: Script names with colons (like test:unit) are automatically converted to valid tool names (test_unit)

• Rich Descriptions: Each tool includes the actual script command in its description

• Package Manager Detection: Automatically detects npm, pnpm, yarn, or bun

• Optional Arguments: Each tool accepts optional args (string or string[]) appended after -- when running the script

• Auto-Restart on Changes: Automatically restarts when package.json or config changes, ensuring tools are always up-to-date

Note: scripts run inside the target project. If they rely on local dependencies (eslint, vitest, tsc), install them first (for example, npm install).

As a CLI Tool

You can also use this package directly from the command line:

Configuration

Setup instructions for AI agents.

GitHub Copilot (VS Code)

Via UI

1. Open VS Code settings

2. Search for "MCP"

3. Add server configuration in settings.json

Via Config File

Option A — per-workspace via .vscode/mcp.json (recommended for multi-project use):

Option B — user settings (settings.json):

Then open Copilot Chat, switch to Agent mode, and start the npm-scripts server from the tools panel.

Cursor

Via UI

1. Open Settings -> MCP Servers -> Add MCP Server

2. Type: NPX Package

3. Command: npx

4. Arguments: -y npm-run-mcp-server

5. Save and start the server from the tools list

Via Config File

Add to Cursor's MCP configuration:

Claude Code

Via Terminal

Via Config File

Add to Claude Code's config file:

• Windows: %APPDATA%/Claude/claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

Restart Claude Code after editing the config.

Multi-Project Workflow

The MCP server automatically detects your project's package.json using workspace environment variables or by walking up from the current working directory. No hardcoded paths needed - it works seamlessly across all your projects.

Auto-Restart on Script Changes

The server automatically monitors your package.json file (and npm-run-mcp.config.json if present) for changes. When you modify scripts or config, the server gracefully exits to allow the MCP client to restart with updated tools.

Script Exposure Config

You can make the tool surface more deterministic by explicitly choosing which scripts are exposed and by defining per-script tool metadata.

Create npm-run-mcp.config.json (or .npm-run-mcp.json) next to your project's package.json:

Notes:

• include and exclude are exact script names.

• toolName lets you resolve naming collisions after sanitization.

• inputSchema extends the default input model (and args is always available).

• Tool input fields (other than args) are converted to CLI flags, e.g. { "watch": true } becomes --watch and { "port": 3000 } becomes --port 3000.

• If filters result in zero tools, the server logs a warning so misconfigurations are easy to spot.

• Config files support JSONC (comments + trailing commas). A JSON Schema is published as npm-run-mcp.config.schema.json.

Install from source (for testing in another project)

Clone, build, and link globally:

In your other project, either reference the global binary or the built file directly:

• Using the linked binary:

• Using an explicit Node command (no global link needed):

Optional CLI flags you can pass in args:

• --cwd /path/to/project to choose which project to read package.json from (rarely needed - server auto-detects by default)

• --pm npm|pnpm|yarn|bun to override package manager detection

Testing with MCP Inspector

Test the server locally.

You should see your package.json scripts listed as available tools. Try running one - it executes the script and returns the output.

CLI Options

Command-line flags.

• --cwd <path> - Specify working directory (defaults to current directory)

• --config <path> - Use an explicit config file path (relative to the project directory, or absolute)

• --pm <manager> - Override package manager detection (npm|pnpm|yarn|bun)

• --verbose - Enable detailed logging to stderr

• --list-scripts - List available scripts and exit

Contributing

Contributions welcome! How to help with development, reporting issues, and submitting changes.

Reporting Issues

• Use the issue tracker to report bugs

• Include your Node.js version, package manager, and operating system

• Provide a minimal reproduction case when possible

Submitting Changes

1. Fork the repository

2. Create a feature branch: git checkout -b feature/amazing-feature

3. Make your changes and add tests if applicable

4. Test your changes: npm run build && npm run test

5. Commit your changes: git commit -m 'Add amazing feature'

6. Push to the branch: git push origin feature/amazing-feature

7. Submit a pull request

Development Setup

The project uses a custom build script located in scripts/build.cjs that handles TypeScript compilation and shebang injection for the executable.

License

MIT License.