MCP Js

What r33drichards/mcp-js MCP server does

r33drichards/mcp-js provides an MCP interface to a JavaScript and TypeScript runtime built on an isolated V8 engine. Agents submit code through run_js, allowing them to perform loops, branching, transformations, asynchronous work, and other logic inside the runtime rather than expressing every operation as a separate tool call.

The server supports two execution styles. Stateful mode preserves JavaScript variables and objects across calls through content-addressed V8 heap snapshots. Stateless mode runs each request independently and returns its output and any error in the response. Console messages are captured and can be read incrementally.

How it works

In stateful mode, run_js queues an execution and returns an execution ID. The client can use that ID to inspect status, retrieve the result, read console output, or stop the job. Output supports pagination by either lines or bytes, which is useful for scripts that produce more output than a single response should contain.

The runtime includes JavaScript and TypeScript support, with TypeScript type syntax removed through SWC rather than type-checked. Promises, async/await, timers, and the standard WebAssembly API are available. Optional preloaded WebAssembly modules can be exposed as globals.

Host access is separated from the JavaScript runtime. Network requests, filesystem operations, subprocesses, external module imports, and calls to other MCP servers are disabled until enabled by configuration and OPA/Rego policy. When enabled, scripts can use fetch, filesystem APIs, subprocess interfaces, external npm:, jsr:, or URL modules, and mcp.callTool() or related MCP helpers.

Setup and configuration

The server can be installed with the project’s shell installer, run through Nix, deployed with Docker, built from source, or deployed using the supplied Railway configuration. Supported installer platforms are Linux x86_64, Linux arm64, and macOS Apple Silicon.

MCP clients can connect through stdio. The server also offers Streamable HTTP and a legacy HTTP+SSE transport. Streamable HTTP uses the /mcp endpoint when an HTTP port is enabled. A REST sidecar exposes script execution at /api/exec, accepting JSON requests or raw script bodies.

Configuration can be supplied with command-line flags or one TOML/JSON file passed to --config. The MCP_V8_CONFIG environment variable can identify that file. Settings take precedence in this order: command-line flags, MCP_V8_* environment variables, configuration-file values, then defaults.

Tools and capabilities

• run_js executes code in stateful or stateless mode.
• get_execution checks the status and result of a stateful execution.
• get_execution_output reads stored console output with line- or byte-based pagination.
• cancel_execution terminates a running execution.
• list_executions lists executions and their statuses.
• Heap snapshots can persist state locally, in S3, or through an S3 write-through cache.
• Policy-controlled integrations include fetch, filesystem access, subprocesses, external modules, and upstream MCP servers.
• JWKS-based JWT verification and optional Raft clustering are available for deployments that need authentication or replicated session metadata.
• Native MCP tasks are supported over Streamable HTTP and stdio for clients that declare the tasks extension.

Limitations and notes

The default policy blocks network, filesystem, subprocess, external module, and upstream MCP access. Enabling these capabilities requires deliberate policy configuration. TypeScript syntax is stripped for execution; the runtime does not perform TypeScript type checking. The legacy SSE transport does not provide the native MCP tasks extension. Stateful operation requires heap storage, while stateless mode avoids persisted execution state.