JavaScript MCP Server (js-mcp)

A Model Context Protocol (MCP) server that allows AI assistants to execute JavaScript code with stateful REPL sessions.

Features

Core Features

• One-time JavaScript Execution: Execute JavaScript code directly in Node.js
• Stateful REPL Sessions: Maintain variables and context across multiple executions
• File System Operations: Read, write, and manipulate files
• Package Management: Import modules and manage npm packages

Advanced Features

• Secure sandboxed execution
• Asynchronous code support
• Error handling with formatted stack traces
• Session management with automatic cleanup

Installation

# Clone the repository
git clone https://github.com/yourusername/js-mcp.git
cd js-mcp

# Install dependencies
npm install

# Build the project
npm run build

Usage

Run with stdio transport (for use with Claude Desktop)

npm start
# or
node dist/index.js --stdio

Run with HTTP transport

node dist/index.js --http
# Default port is 3000, or specify with PORT environment variable
PORT=3456 node dist/index.js --http

Available Tools

JavaScript Execution

• execute_javascript: Run JavaScript code in a basic sandbox
• execute_javascript_with_modules: Run JavaScript with module imports
• execute_javascript_async: Run asynchronous JavaScript code

REPL Sessions

• repl_create_session: Create a new REPL session
• repl_execute: Execute code in a REPL session
• repl_get_context: Get variable values in a session
• repl_delete_session: Delete a session
• repl_list_sessions: List all active sessions

File Operations

• file_read: Read file contents
• file_write: Write content to a file
• file_list: List files in a directory
• file_delete: Delete a file or directory
• file_exists: Check if a file exists

Package Management

• package_check: Check if a module is available
• package_install: Install an npm package
• package_list: List installed packages

Security

The server uses direct JavaScript execution with safety features:

• Timeout limits for code execution
• File system access limited to working directory
• Path validation to prevent dangerous operations

Configuration

Configure the server by setting environment variables:

• PORT: HTTP server port (default: 3000)
• WORKING_DIRECTORY: Base directory for file operations (default: current directory)
• SESSION_TIMEOUT: REPL session timeout in minutes (default: 30)

Development

# Start in development mode
npm run dev

# Run tests
npm test

# Lint code
npm run lint

# Format code
npm run format

License

MIT