{
  "markdown": "# npm-run-mcp-server\n\n<div align=\"center\">\n\n*Give your AI Agent the power to build, test, and deploy your project using your existing package.json scripts.*\n\n[![Test](https://github.com/fstubner/npm-run-mcp-server/workflows/Test/badge.svg)](https://github.com/fstubner/npm-run-mcp-server/actions/workflows/test.yml)\n[![Build & Publish](https://github.com/fstubner/npm-run-mcp-server/workflows/Build%20&%20Publish/badge.svg)](https://github.com/fstubner/npm-run-mcp-server/actions/workflows/build-and-publish.yml)\n[![NPM Version](https://img.shields.io/npm/v/npm-run-mcp-server.svg)](https://www.npmjs.com/package/npm-run-mcp-server)\n[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-Listed-blue)](https://registry.modelcontextprotocol.io)\n[![Install in Cursor](https://img.shields.io/badge/Install_in-Cursor-000000?style=flat-square&logoColor=white)](https://cursor.com/en/install-mcp?name=npm-scripts&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIm5wbS1ydW4tbWNwLXNlcnZlciJdfQ==)\n[![Install in VS Code](https://img.shields.io/badge/Install_in-VS_Code-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](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)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n  <a href=\"https://glama.ai/mcp/servers/@fstubner/npm-run-mcp-server\">\n    <img width=\"380\" height=\"200\" src=\"https://glama.ai/mcp/servers/@fstubner/npm-run-mcp-server/badge\" alt=\"npm-run-mcp-server MCP server\" />\n  </a>\n  <br><br>\n</div>\n\n**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.\n\n- 🔍 **Auto-detects** your project's `package.json` (no hardcoded paths).\n- 📦 **Works with everything**: npm, pnpm, yarn, and bun.\n- 🔒 **Safe & Configurable**: Whitelist specific scripts to prevent accidental execution.\n- ⚡ **Zero-config**: Works out of the box, but scales with detailed config.\n\n---\n\n## ⚡ Quick Start\n\nConnect your agent to your scripts in seconds. No global installation required—just let `npx` handle it.\n\n### Claude Desktop\nAdd this to your `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"npm-scripts\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"npm-run-mcp-server\"]\n    }\n  }\n}\n```\n\n### Cursor\n\n[![Install in Cursor](https://img.shields.io/badge/Install_in-Cursor-000000?style=flat-square&logoColor=white)](https://cursor.com/en/install-mcp?name=npm-scripts&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIm5wbS1ydW4tbWNwLXNlcnZlciJdfQ==)\n\n1. Go to **Settings** > **Features** > **MCP Servers**.\n2. Click **+ Add New MCP Server**.\n3. Enter the details:\n   - **Type**: `command`\n   - **Name**: `npm-scripts`\n   - **Command**: `npx`\n   - **Args**: `-y npm-run-mcp-server`\n\n### VS Code (GitHub Copilot)\n\n[![Install in VS Code](https://img.shields.io/badge/Install_in-VS_Code-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](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)\n\nAdd this to your workspace `.vscode/settings.json`:\n\n```json\n{\n  \"github.copilot.chat.mcpServers\": {\n    \"npm-scripts\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"npm-run-mcp-server\"]\n    }\n  }\n}\n```\n\n---\n\n## 🛠️ Configuration\n\nWhile `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.\n\n### Example Config\nCreate `npm-run-mcp.config.json` next to your `package.json`:\n\n```json\n{\n  \"include\": [\"test\", \"lint\", \"build\", \"start\"],\n  \"scripts\": {\n    \"test\": {\n      \"description\": \"Run the test suite. Use --watch for interactive mode.\",\n      \"inputSchema\": {\n        \"properties\": {\n          \"watch\": { \"type\": \"boolean\", \"description\": \"Watch files for changes\" }\n        }\n      }\n    }\n  }\n}\n```\n\n### Configuration Options\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `include` | `string[]` | Whitelist of script names to expose. If omitted, *all* scripts are exposed. |\n| `exclude` | `string[]` | Blacklist of script names to hide. |\n| `scripts` | `object` | Detailed configuration for specific scripts. |\n\n#### Per-Script Options\nInside the `scripts` object, you can map a script name to:\n\n- `toolName`: Override the tool name seen by the AI (e.g., rename `test:unit` to `run_unit_tests`).\n- `description`: Provide a custom description to help the AI understand when to use this script.\n- `inputSchema`: Define strictly typed arguments that the AI can pass (mapped to CLI flags).\n\n---\n\n## 📖 How It Works\n\n1. **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.\n2. **Tool Creation**: It converts your scripts into MCP Tools.\n   - Scripts like `test:unit` become tools like `test_unit`.\n   - The tool description includes the actual command (e.g., `vitest run`) so the AI knows what it's running.\n3. **Execution**: When the AI calls a tool, the server executes the script in your project's root directory using the detected package manager.\n\n---\n\n## 🔧 Advanced / CLI Usage\n\nYou can run the server manually for debugging or if you need to pass specific flags.\n\n```bash\n# Run directly\nnpx npm-run-mcp-server --list-scripts\n\n# Run in a specific directory\nnpx npm-run-mcp-server --cwd /path/to/project\n\n# Force a specific package manager\nnpx npm-run-mcp-server --pm pnpm\n```\n\n### CLI Flags\n- `--cwd <path>`: Manually set the working directory.\n- `--pm <npm|pnpm|yarn|bun>`: Force a specific package manager.\n- `--config <path>`: Path to a specific JSON config file.\n- `--verbose`: Print debug logs to stderr.\n\n---\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repo.\n2. Create your feature branch (`git checkout -b feature/amazing-feature`).\n3. Commit your changes (`git commit -m 'Add some amazing feature'`).\n4. Push to the branch (`git push origin feature/amazing-feature`).\n5. Open a Pull Request.\n\n## License\n\nMIT © [Felix Stubner](https://github.com/fstubner)\n",
  "bytes": 6399,
  "sha": "2fcaeb72c765846d51e2c0642157631fbbce935230f5844fb111f4ab857affa1",
  "repo_slug": "fstubner/npm-run-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_fstubner_npm_run_mcp_server_32a1fa86/readme"
}