Content
# Node Runner MCP Server
[](https://nodejs.org/)
An MCP server that allows you to run Node.js scripts and npm commands, with permission prompts via [`node-notifier`](https://www.npmjs.com/package/node-notifier).
## Requirements
- Node.js >= 22.0.0
## Features
- Run Node.js scripts with arguments and standard input
- Execute npm scripts from package.json files with standard input
- Run JavaScript code directly with Node's eval and provide standard input
- Start Node.js servers that continue running in the background
- List running servers and view their status
- Stop running servers gracefully or forcefully when needed
- Retrieve and filter server logs for debugging and monitoring
- Select specific Node.js versions using NVM
- View available npm scripts in package.json files
- Fetch documentation for npm packages with README and metadata
- Permission prompts before any execution (can be disabled)
## Setup
1. Clone this repository
2. Install dependencies:
```bash
npm install
```
3. Build the TypeScript code:
```bash
npm run build
```
## Project Structure
- `src/index.ts` - Main MCP server implementation
- `test.js` - Sample test script to run with the server
## Usage with Claude for Desktop
1. Build the project with `npm run build`
2. Add the server to your Claude for Desktop configuration:
```json
{
"mcpServers": {
"node-runner": {
"command": "npx",
"args": ["-y", "mcp-node@latest"],
"env": {
"DISABLE_NOTIFICATIONS": "true", // Optional: disable permission prompts
"EVAL_DIRECTORIES": "/path/to/safe/dir1:/path/to/safe/dir2" // Optional: additional allowed eval directories
}
}
}
}
```
3. Restart Claude for Desktop
4. You can now ask Claude to run Node.js scripts or npm commands
5. (Optional) Use the `env` configuration to disable notification prompts as shown above
## Available Tools
### start-node-server
Starts a Node.js server that continues running in the background, even after the command completes.
Parameters:
- `scriptPath`: Path to the Node.js server script to execute
- `cwd`: Directory to run the server in
- `serverName`: (Optional) Friendly name for the server (defaults to the script filename)
- `nodeArgs`: (Optional) Arguments to pass to the Node.js executable itself
- `args`: (Optional) Array of arguments to pass to the server script
Example prompt: "Start an Express server from server.js and keep it running"
Example usage:
```javascript
start-node-server({
scriptPath: "/absolute/path/to/server.js",
cwd: "/absolute/path/to/project",
serverName: "My Express API",
args: ["--port", "3000"]
});
```
### list-servers
Lists all running Node.js servers started via the MCP server.
Parameters:
- `showLogs`: (Optional) Boolean to include recent logs in the output (default: false)
- `serverId`: (Optional) Server ID to get details for a specific server
Example prompt: "Show me all running Node.js servers"
Example to view detailed logs for a specific server:
```javascript
list-servers({
serverId: "server-1234567890-1234",
showLogs: true
});
```
### stop-server
Stops a running Node.js server.
Parameters:
- `serverId`: ID of the server to stop
- `force`: (Optional) Boolean to force kill the server with SIGKILL instead of SIGTERM (default: false)
Example prompt: "Stop the Node.js server with ID server-1234567890-1234"
Example to forcefully terminate a server:
```javascript
stop-server({
serverId: "server-1234567890-1234",
force: true
});
```
### get-server-logs
Retrieves the last N lines of logs from a running server with filtering options. This tool is essential for debugging and monitoring server behavior without having to stop it.
Parameters:
- `serverId`: ID of the server to get logs from
- `lines`: (Optional) Number of log lines to retrieve (default: 50)
- `filter`: (Optional) String to filter logs (case-insensitive)
- `stdout`: (Optional) Boolean to include stdout logs (default: true)
- `stderr`: (Optional) Boolean to include stderr logs (default: true)
Key features:
- Retrieves logs from both running and exited servers
- Filters logs to show only stdout or stderr as needed
- Searches for specific text within logs
- Shows server status alongside the logs
- Limits output to exactly the number of lines requested
Example prompt: "Show me the last 100 logs from the server with ID server-1234567890-1234"
Example to view only error output:
```javascript
get-server-logs({
serverId: "server-1234567890-1234",
stderr: true,
stdout: false
});
```
Example with text filtering:
```javascript
get-server-logs({
serverId: "server-1234567890-1234",
lines: 100,
filter: "error"
});
```
### run-node-script
Executes a Node.js script file.
Parameters:
- `scriptPath`: Path to the Node.js script to execute
- `nodeArgs`: (Optional) Arguments to pass to the Node.js executable itself
- `args`: (Optional) Array of arguments to pass to the script
- `stdin`: (Optional) Text to provide as standard input to the script
- `cwd`: (Optional) Directory to run the script in (defaults to OS temp directory if not specified)
- `timeout`: (Optional) Timeout in milliseconds after which the process is killed (defaults to 60000ms)
Example prompt: "Run the test.js script with arguments 'hello' and 'world'"
Example with working directory:
```javascript
run-node-script({
scriptPath: "/absolute/path/to/my-script.js",
args: ["arg1", "arg2"],
cwd: "/absolute/path/to/project"
});
```
Example with timeout:
```javascript
run-node-script({
scriptPath: "/absolute/path/to/long-running-script.js",
timeout: 10000 // Kill after 10 seconds
});
```
### run-npm-script
Executes an npm script from a package.json file.
Parameters:
- `packageDir`: Directory containing the package.json
- `scriptName`: Name of the script to run
- `args`: (Optional) Array of arguments to pass to the script
- `stdin`: (Optional) Text to provide as standard input to the script
Example prompt: "Run the 'start' script from the package.json in the current directory"
### run-npm-install
Executes npm install to install all dependencies or a specific package.
Parameters:
- `packageDir`: Directory containing package.json
- `dependency`: (Optional) Specific dependency to install (leave empty to install all dependencies from package.json)
Example prompt: "Install express in the current project"
Example usage:
```javascript
run-npm-install({
packageDir: "/absolute/path/to/project",
dependency: "express"
});
```
### run-node-eval
Executes JavaScript code directly.
Parameters:
- `code`: JavaScript code to execute
- `evalDirectory`: (Optional) Directory to execute the code in
- `stdin`: (Optional) Text to provide as standard input to the code
- `timeout`: (Optional) Timeout in milliseconds after which the process is killed (defaults to 5000ms)
Example prompt: "Run this JavaScript code: console.log('Hello world');"
Example with timeout:
```javascript
run-node-eval({
code: `
// This code would be terminated after 3 seconds
console.log('Starting long operation...');
setTimeout(() => {
console.log('This will never be logged');
}, 5000);
`,
timeout: 3000 // Kill after 3 seconds
});
```
### fetch-npm-docs
Fetches documentation for an npm module, including README and metadata. Downloads the package, extracts the README, and caches results to avoid redundant downloads.
Parameters:
- `packageName`: Name of the npm package
- `version`: (Optional) Specific version to fetch (defaults to latest)
Key features:
- Retrieves package metadata using `npm view`
- Downloads and extracts the package tarball to get the README
- Caches packages both in memory and on disk to avoid redundant downloads
- Works with the selected Node.js version
Example prompt: "Show me the documentation for the express package"
Example usage:
```javascript
fetch-npm-docs({
packageName: "express",
version: "4.18.2"
});
```
### list-node-versions
Lists all available Node.js versions installed via NVM (Node Version Manager).
Parameters: None
Example prompt: "Show me all installed Node.js versions"
### select-node-version
Selects a specific Node.js version to use for subsequent script executions.
Parameters:
- `version`: Node.js version to use (e.g., 'v18.20.5', 'system', 'lts/*', or other NVM aliases)
Example prompt: "Use Node.js version 18 for running scripts"
### get-node-version
Displays information about the currently selected Node.js version.
Parameters: None
Example prompt: "What Node.js version is currently being used?"
## Examples of Using Standard Input
### Passing Input to a Node Script
```javascript
// Example script: process-data.js
process.stdin.on('data', (data) => {
const input = data.toString().trim();
console.log(`Received: ${input}`);
// Process the input...
});
```
You can execute this with standard input and a specific working directory:
```
run-node-script({
scriptPath: "/absolute/path/to/process-data.js",
stdin: "This is input data",
cwd: "/absolute/path/to/my-project-directory" // Sets the working directory for the script
});
```
### Using Standard Input with Eval
```
run-node-eval({
code: `
let data = '';
process.stdin.on('data', (chunk) => { data += chunk; });
process.stdin.on('end', () => {
console.log('Received:', data);
});
`,
stdin: "Data to process"
});
```
### Reading a File Then Using It As Standard Input
```
// First read the file
const fileContent = read_file({ path: "/absolute/path/to/data.txt" });
// Then pass it as standard input to a script
run-node-script({
scriptPath: "/absolute/path/to/process-data.js",
stdin: fileContent,
cwd: "/absolute/path/to/working-directory"
});
```
## Server Management and Monitoring
This MCP server provides a complete solution for running and monitoring Node.js servers in the background:
1. **Starting Servers**: Use `start-node-server` to launch servers that keep running even after the command completes.
2. **Monitoring**: Monitor server logs in real-time with `get-server-logs` to keep track of activity and troubleshoot issues.
3. **Process Management**: View all running servers with `list-servers` and get detailed information about their status.
4. **Graceful Shutdown**: Stop servers gracefully with `stop-server`, preserving any in-flight operations.
### Example Server Monitoring Workflow:
```javascript
// 1. Start a server
const serverInfo = start-node-server({
scriptPath: "/path/to/server.js",
cwd: "/path/to/project",
serverName: "API Server"
});
// Extract server ID from the response
const serverId = serverInfo.content[0].text.match(/Server ID: ([\w-]+)/)[1];
// 2. Monitor logs in real-time (periodic polling)
get-server-logs({
serverId: serverId,
lines: 20
});
// 3. Filter logs for errors only
get-server-logs({
serverId: serverId,
filter: "error",
lines: 50
});
// 4. When finished, stop the server
stop-server({
serverId: serverId
});
```
### Debugging Complex Issues:
When troubleshooting server issues, you can use a combination of tools:
1. Check server status with `list-servers`
2. View filtered logs with `get-server-logs`
3. If the server is unresponsive, force stop it with `stop-server({ serverId, force: true })`
## Resources
### node-version
Displays information about the Node.js environment running the MCP server.
URI template: `node-version://info`
Example prompt: "What version of Node.js is being used to run the scripts?"
### npm-scripts
Lists all available npm scripts in a package.json file.
URI template: `npm-scripts://{directory}`
Example prompt: "Show me the available npm scripts in this project"
## Security Considerations
- The server will always prompt for permission before executing any command
- Scripts run with the same permissions as the MCP server process
- Be cautious when running scripts from untrusted sources
## Environment Variables
### DISABLE_NOTIFICATIONS
Set `DISABLE_NOTIFICATIONS=true` to automatically approve all permission requests without showing notification prompts:
```bash
# Run with notifications disabled
DISABLE_NOTIFICATIONS=true npm run dev
```
This is useful for automation scenarios or when you don't want to be prompted for each action.
### EVAL_DIRECTORIES
Specify a colon-separated list of directories where JavaScript code can be evaluated using the `run-node-eval` tool:
```bash
# Allow code evaluation in specific directories
EVAL_DIRECTORIES=/path/to/dir1:/path/to/dir2 npm run dev
```
By default, only the system temporary directory is allowed. This environment variable lets you add additional safe directories.
## License
MIT
Connection Info
You Might Also Like
MarkItDown MCP
Converting files and office documents to Markdown.
Time
Obtaining current time information and converting time between different...
Filesystem
Model Context Protocol Servers
Sequential Thinking
Offers a structured approach to dynamic and reflective problem-solving,...
Git
Model Context Protocol Servers
Context 7
Context7 MCP Server -- Up-to-date code documentation for LLMs and AI code editors