Npm Run Mcp Server

io.github.fstubner由 GitHub 帳號 fstubner 發布v0.2.13更新於 Oct 24, 2026

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

已驗證STDIO僅桌面效率與工作流開發者工具

概覽

AI 產生的概覽

一個本機 MCP 伺服器,把專案的 package.json 指令碼變成工具,讓助理執行建置、測試、程式碼檢查與啟動等任務。

可以做什麼
自動偵測專案的 package.json,並將其指令碼公開為工具,工具名稱由指令碼名稱轉換而來(例如 test:unit 變成 test_unit)。在工具說明中顯示實際執行的指令,讓助理知道執行的是什麼。使用偵測到的套件管理工具(npm、pnpm、yarn 或 bun)在專案根目錄執行所選指令碼。可透過設定檔限制公開的指令碼,並為個別指令碼設定自訂名稱、說明與具型別的參數。
適用情境
適合希望助理直接執行現有建置、測試、程式碼檢查或啟動指令碼的 JavaScript 或 TypeScript 專案。適用於本機開發情境,讓助理觸發專案任務而不必手動複製指令。
執行需求
以本機 stdio 程序執行,通常透過 npx 啟動,因此需要 Node.js 與 npm。工作區中必須有 package.json,或以 --cwd 參數指定工作目錄。未宣告需要帳號、API 金鑰或環境變數。
安裝前請注意
預設會公開全部 package.json 指令碼,包括 eject 或 publish 之類的指令碼;應使用 include 或 exclude 設定加以限制。呼叫工具會在專案根目錄執行指令碼,可能修改檔案、安裝套件或部署,使用前請先確認每個指令碼的作用。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Npm Run Mcp Server,將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Desktop only,透過 STDIO。 STDIO 服務會啟動本機處理程序,因此需要 SourceWeft 桌面主機。

其他 MCP 客戶端

參照 儲存庫 中的啟動說明。

README

npm-run-mcp-server

Give your AI Agent the power to build, test, and deploy your project using your existing package.json scripts.

[Test] [Build & Publish] [NPM Version] [MCP Registry] [Install in Cursor] [Install in VS Code] [License: MIT]

[npm-run-mcp-server MCP server]

npm-run-mcp-server is a Model Context Protocol (MCP) 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

[Install in Cursor]

  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)

[Install in VS Code]

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

FieldTypeDescription
includestring[]Whitelist of script names to expose. If omitted, all scripts are exposed.
excludestring[]Blacklist of script names to hide.
scriptsobjectDetailed 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 directlynpx npm-run-mcp-server --list-scripts
# Run in a specific directorynpx npm-run-mcp-server --cwd /path/to/project
# Force a specific package managernpx 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

來源:README.md,提交 8268fac

工具

0
SourceWeft 尚未在沙箱中啟動過該軟體包,因此其工具未知。

版本歷史

1
  1. v0.2.13最新Sep 16, 2026

評分

已滿足適用檢查項的 50%

該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通25 分

    請保持端點能夠回應 MCP 握手;SourceWeft 每 30 天探測一次。

  • 已宣告認證方式10 分

    請在註冊中心條目中宣告憑證請求標頭,或保持端點能夠回應探測,以便判定其認證方式。

  • 已列出工具15 分

    請讓伺服器在無憑證時回應 tools/list,或發布可在沙箱中無憑證啟動的軟體包。

  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分