MCP Js

What r33drichards/mcp-js MCP server does

The r33drichards/mcp-js MCP server exposes a JavaScript and TypeScript runtime to AI agents through Model Context Protocol. Code runs inside an isolated V8 engine provided through deno_core. TypeScript syntax is supported by removing types with SWC; the runtime does not perform type checking.

The central run_js tool accepts agent-generated code. In stateful mode, it queues work and returns an execution ID. In stateless mode, it runs the script and returns its output, with an optional error. Stateful sessions can preserve variables and objects through content-addressed V8 heap snapshots, allowing later executions to continue from prior state.

How it works

The server captures console activity from console.log, info, warn, error, debug, and trace. For queued executions, an agent can use get_execution to inspect status and results, get_execution_output to read console output by line or byte ranges, cancel_execution to stop active work, and list_executions to review execution states.

JavaScript includes asynchronous promises, timers, and the standard WebAssembly API. Optional globals provide access to HTTP requests, filesystem operations, subprocesses, external ES module imports, and other MCP servers. These host capabilities are disabled by default and require explicit OPA/Rego policy permissions. External imports can use npm:, jsr:, or URL-based modules when module access is enabled.

The r33drichards/mcp-js MCP server supports stdio, Streamable HTTP, and legacy HTTP+SSE transports. Streamable HTTP and stdio also support MCP tasks for clients that implement them. An HTTP deployment can expose both the MCP endpoint and a REST execution sidecar.

Setup and configuration

The repository provides an install script for Linux x86_64, Linux arm64, and macOS Apple Silicon. Other supported installation paths include Nix, Docker, building from source, and a Railway deployment configuration. The server can be connected to Claude Code with its claude mcp add command, or configured in Claude Desktop and Cursor through an mcpServers entry.

Run mcp-v8 --stateless --http-port 8080 to expose the MCP endpoint at /mcp and the REST sidecar at /api/exec. Stateful operation requires a heap directory or another configured heap store. A TOML or JSON file passed with --config can contain the server settings, and MCP_V8_CONFIG can identify that file. Configuration precedence is command-line flags, then MCP_V8_* environment variables, then the configuration file, then defaults.

Tools and capabilities

The r33drichards/mcp-js MCP server provides these MCP tools:

• run_js executes code in stateful or stateless mode.
• get_execution polls a stateful execution.
• get_execution_output reads paginated console output.
• cancel_execution terminates a running execution.
• list_executions lists executions and their statuses.

Additional configuration can preload WebAssembly modules, customize server instructions and the run_js description, connect upstream MCP servers through JavaScript, and configure JWKS-based JWT verification or Raft-based clustering. Heap snapshots can use local storage, S3, or S3 with a write-through cache.

Limitations and notes

Stateful execution and its management tools depend on the configured session and heap storage; stateless mode does not provide persistent execution state. Filesystem, network, subprocess, external-module, and upstream-MCP access are not available unless their policies and related options permit them. The optional operating-system sandbox manifest adds confinement beneath the policy layer, using Landlock on Linux or Seatbelt on macOS. The legacy SSE transport does not provide MCP tasks.