npm-run-mcp-server

Table of Contents

• Install
• Usage
• Configuration
  • GitHub Copilot Chat (VS Code)
  • Claude Code (VS Code extension)
  • Claude Code (terminal / standalone)
  • Cursor
  • Install from source
• Testing with MCP Inspector
• CLI Options
• Contributing
• License

Install

npm i -D npm-run-mcp-server
# or globally
npm i -g npm-run-mcp-server
# ad-hoc
npx npm-run-mcp-server

Usage

As an MCP Server

Add this server to your MCP host configuration. It uses stdio and dynamically exposes each script from the closest package.json (walking up from process.cwd()).

The tool names match your script names. Each tool accepts an optional args string that is appended after -- when running the script. The server detects your package manager (npm, pnpm, yarn, bun).

As a CLI Tool

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

# List available scripts in current directory
npx npm-run-mcp-server --list-scripts

# Run with verbose output
npx npm-run-mcp-server --verbose

# Specify a different working directory
npx npm-run-mcp-server --cwd /path/to/project --list-scripts

# Override package manager detection
npx npm-run-mcp-server --pm yarn --list-scripts

Configuration

Install in GitHub Copilot Chat (VS Code)

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

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

Option B — user settings (settings.json):

{
  "mcp.servers": {
    "npm-scripts": {
      "command": "npx",
      "args": ["-y", "npm-run-mcp-server"]
    }
  }
}

Note: The server automatically detects the current project's package.json using process.cwd(), so no hardcoded paths are needed. It works seamlessly across all your projects.

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

Multi-Project Workflow

The MCP server is designed to work seamlessly across multiple projects without configuration changes:

• VS Code/Cursor: Use workspace settings (.vscode/mcp.json or .vscode/settings.json) - the server automatically targets the current project
• Claude Desktop: The server uses the working directory where Claude is launched
• No Hardcoded Paths: All examples use npx npm-run-mcp-server without --cwd flags
• Automatic Detection: The server walks up the directory tree to find the nearest package.json

This means you can use the same MCP configuration across all your projects, and the server will automatically target the correct project based on where your MCP client is running.

Install in Claude Code (VS Code extension)

Add to VS Code user/workspace settings (settings.json):

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

Note: Workspace settings (.vscode/settings.json) are recommended for multi-project use, as they automatically target the current project.

Restart the extension and confirm the server/tools appear.

Install in Claude Code (terminal / standalone)

Add this server to Claude's global config file (paths vary by OS). Create the file if it doesn't exist.

• Windows: %APPDATA%/Claude/claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Recommended approach - Using npx (works across all projects):

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

Alternative - Using a local build (requires absolute path):

{
  "mcpServers": {
    "npm-scripts": {
      "command": "node",
      "args": ["/absolute/path/to/npm-run-mcp-server/dist/index.js"]
    }
  }
}

Note: The npx approach is recommended as it automatically targets the current working directory where Claude is launched.

Optional: include environment variables

{
  "mcpServers": {
    "npm-scripts": {
      "command": "npx",
      "args": ["-y", "npm-run-mcp-server"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

Restart Claude after editing the config so it picks up the new server.

Install in Cursor

• Open Settings → MCP Servers → Add MCP Server
• Type: NPX Package
• Command: npx
• Arguments: -y npm-run-mcp-server
• Save and start the server from the tools list

Note: This configuration automatically works across all your projects. The server will target the current project's package.json wherever Cursor is opened.

Install from source (for testing in another project)

Clone, build, and link globally:

git clone https://github.com/your-org-or-user/npm-run-mcp-server.git
cd npm-run-mcp-server
npm install
npm run build
npm link

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

• Using the linked binary:

{
  "servers": {
    "npm-scripts": {
      "command": "npm-run-mcp-server"
    }
  }
}

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

{
  "servers": {
    "npm-scripts": {
      "command": "node",
      "args": ["/absolute/path/to/npm-run-mcp-server/dist/index.js"]
    }
  }
}

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 before integrating with AI agents:

# Start MCP Inspector
npx @modelcontextprotocol/inspector

# In the Inspector UI:
# 1. Transport Type: STDIO
# 2. Command: npx
# 3. Arguments: npm-run-mcp-server --cwd /path/to/your/project --verbose
# 4. Click "Connect"

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

CLI Options

Available command-line flags:

• --cwd <path> - Specify working directory (defaults to current directory)
• --pm <manager> - Override package manager detection (npm|pnpm|yarn|bun)
• --verbose - Enable detailed logging to stderr
• --list-scripts - List available scripts and exit

Contributing

We welcome contributions! Here's how you can help:

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

git clone https://github.com/fstubner/npm-run-mcp-server.git
cd npm-run-mcp-server
npm install
npm run build
npm run test

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

Guidelines

• Follow the existing code style
• Add tests for new features
• Update documentation as needed
• Keep commits focused and descriptive

License

MIT