r33drichards/mcp-js

**mcp-v8** is a Model Context Protocol server,
written in Rust, that lets an AI agent **run JavaScript and TypeScript in a
sandboxed V8 isolate**. Instead of wiring up dozens of narrow tools, you give the
agent one tool — run_js — and it writes code: looping, branching, transforming
data, and calling other tools, often with far fewer tokens than equivalent
tool-call chains.
In its default *stateful* mode the V8 heap is saved as a content-addressed
snapshot, so an agent can build up state across many turns. Host capabilities
(network, filesystem, subprocess, WebAssembly, module imports, and calls to other
MCP servers) are all **off by default** and unlocked only by explicit
OPA/Rego policies.
Why mcp-v8
- **One tool, unbounded capability.** The agent runs a program, not a fixed menu of tools.
- **Durable state.** Heap snapshots persist variables and objects across calls.
- **Secure by default.** fetch, filesystem, subprocess, and external imports are denied until you grant them via policy.
- **Kernel-enforced confinement.** Opt-in --sandbox-manifest confines the whole process with a nono capability manifest (Landlock on Linux, Seatbelt on macOS) as defense in depth beneath the policy layer.
- **Production-ready.** stdio / Streamable HTTP / SSE transports, a REST sidecar, async execution with pagination, JWKS auth, and Raft-replicated clustering.
Documentation
Maintainers: see Publishing to the MCP Registry for
the Docker-backed registry manifest and automated release process.
Full documentation lives at ** ** (built
from site-docs/) — tutorials, how-to guides, concept
explanations, and complete reference for the CLI flags,
HTTP API, and
MCP tools.
Quick start
Install
Installs to /usr/local/bin. Supported platforms: Linux x86_64/arm64 and macOS
Apple Silicon. You can also nix run github:r33drichards/mcp-js, use Docker (see
the docker-compose.*.yml stacks), or build from source.
Prefer a hosted server? Deploy on Railway — the repo's
railway.json configures the build, healthcheck, and restart policy, and
RAILWAY.md walks through the volume, variables, and one-click
template setup.
Connect an MCP client
For Claude Desktop / Cursor, add to the client's mcpServers config:
Then ask the agent: *"Run this JavaScript: console.log([1,2,3].map(x => x*2))"*.
Run over HTTP
/api/exec accepts either a JSON body or a raw-body file upload — send the
script as the request body with a non-JSON Content-Type
(curl --data-binary @script.js -H 'Content-Type: application/javascript' .../api/exec).
The run_js MCP tool can also read a script from a path on the server itself
via an optional file parameter — off by default, enabled with
--allow-run-js-file or a run_js_file
policy.
See the Quick Start tutorials and the
transports guide for more.
Configure with a single file
Every flag can also live in one TOML or JSON file passed via --config (or
MCP_V8_CONFIG), including structured sections that replace the separate
WASM / MCP-server / fetch-header / policy JSON files:
Precedence is CLI flag > MCP_V8_* env var > config file > default. See the
configuration file reference.
Features
- **JavaScript & TypeScript** in an isolated V8 engine (via deno_core); TypeScript types are stripped with SWC (type removal, not type checking).
- **Async/await & timers** — Promises and the event loop, plus setTimeout/clearTimeout.
- **Console capture** — console.log/info/warn/error/debug/trace, streamed to storage and readable with line- or byte-based pagination.
- **Async execution model** — run_js returns an execution ID; poll status and stream output; cancel running work.
- **Content-addressed heap snapshots** — persist/restore V8 state across calls (local FS, S3, or S3 + write-through cache), or run **stateless**.
- **WebAssembly** — the standard WebAssembly API, plus pre-loaded modules (--wasm-module) exposed as globals and advertised to clients as runjs__wasm__ stub tools.
- **ES module imports** — optional npm:, jsr:, and URL imports fetched at runtime (policy-gated).