io.github.fstubner/npm-run-mcp-server
An MCP server that exposes package.json scripts as tools for agents.
Open source Open in the app JSON README (API)
About
An MCP server that exposes package.json scripts as tools for agents.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- fstubner
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.2.13
- Stars
- 3
- Forks
- 1
- Open pull requests
- 6
- Last push
- 2026-04-08T11:07:56Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 03:02:48
- Updated
- 2026-08-29 03:02:48
- Origin id
io.github.fstubner/npm-run-mcp-server
README
# npm-run-mcp-server
<div align="center">
*Give your AI Agent the power to build, test, and deploy your project using your existing package.json scripts.*
[](https://github.com/fstubner/npm-run-mcp-server/actions/workflows/test.yml)
[](https://github.com/fstubner/npm-run-mcp-server/actions/workflows/build-and-publish.yml)
[](https://www.npmjs.com/package/npm-run-mcp-server)
[](https://registry.modelcontextprotocol.io)
[](https://cursor.com/en/install-mcp?name=npm-scripts&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIm5wbS1ydW4tbWNwLXNlcnZlciJdfQ==)
[](https://vscode.dev/redirect/mcp/install?name=npm-scripts&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22npm-run-mcp-server%22%5D%7D)
[](https://opensource.org/licenses/MIT)
<a href="https://glama.ai/mcp/servers/@fstubner/npm-run-mcp-server">
<img width="380" height="200" src="https://glama.ai/mcp/servers/@fstubner/npm-run-mcp-server/badge" alt="npm-run-mcp-server MCP server" />
</a>
<br><br>
</div>
**npm-run-mcp-server** is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 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`:
```json
{
"mcpServers": {
"npm-scripts": {
"command": "npx",
"args": ["-y", "npm-run-mcp-server"]
}
}
}
```
### Cursor
[](https://cursor.com/en/install-mcp?name=npm-scripts&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIm5wbS1ydW4tbWNwLXNlcnZlciJdfQ==)
1. Go to **Settings** > **Features** > **MCP Servers**.
2. Click **+ Add New MCP Server**.
3. Enter the details:
- **Type**: `command`
- **Name**: `npm-scripts`
- **Command**: `npx`
- **Args**: `-y npm-run-mcp-server`
### VS Code (GitHub Copilot)
[](https://vscode.dev/redirect/mcp/install?name=npm-scripts&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22npm-run-mcp-server%22%5D%7D)
Add this to your workspace `.vscode/settings.json`:
```json
{
"github.copilot.chat.mcpServers": {
"npm-scripts": {
"command": "npx",
"args": ["-y", "npm-run-mcp-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`:
```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 |
|-------|------|-------------|
| `include` | `string[]` | Whitelist of script names to expose. If omitted, *all* scripts are exposed. |
| `exclude` | `string[]` | Blacklist of script names to hide. |
| `scripts` | `object` | 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., 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).
---
## 📖 How It Works
1. **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.
2. **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.
3. **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.
```bash
# 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
```
### CLI 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.
1. Fork the repo.
2. Create your feature branch (`git checkout -b feature/amazing-feature`).
3. Commit your changes (`git commit -m 'Add some amazing feature'`).
4. Push to the branch (`git push origin feature/amazing-feature`).
5. Open a Pull Request.
## License
MIT © [Felix Stubner](https://github.com/fstubner)