mcp-v8: V8 JavaScript MCP Server

A Rust-based Model Context Protocol (MCP) server that exposes a V8 JavaScript runtime as a tool for AI agents like Claude and Cursor. Supports persistent heap snapshots via S3 or local filesystem, and is ready for integration with modern AI development environments.

Features

• V8 JavaScript Execution: Run arbitrary JavaScript code in a secure, isolated V8 engine.

• Heap Snapshots: Persist and restore V8 heap state between runs, supporting both S3 and local file storage.

• MCP Protocol: Implements the Model Context Protocol for seamless tool integration with Claude, Cursor, and other MCP clients.

• Configurable Storage: Choose between S3 or local directory for heap storage at runtime.

Installation

Install mcp-v8 using the provided install script:

This will automatically download and install the latest release for your platform to /usr/local/bin/mcp-v8 (you may be prompted for your password).

Advanced users: If you prefer to build from source, see the

Command Line Arguments

mcp-v8 supports the following command line arguments:

• --s3-bucket <bucket>: Use AWS S3 for heap snapshots. Specify the S3 bucket name. (Conflicts with --directory-path)

• --directory-path <path>: Use a local directory for heap snapshots. Specify the directory path. (Conflicts with --s3-bucket)

Note: You must specify either --s3-bucket or --directory-path. If neither is provided, the server defaults to S3 with the bucket name test-mcp-js-bucket.

Quick Start

After installation, you can run the server directly. Choose one of the following options:

Integration

Claude for Desktop

1. Install the server as above.

2. Open Claude Desktop → Settings → Developer → Edit Config.

3. Add your server to claude_desktop_config.json:

4. Restart Claude Desktop. The new tools will appear under the hammer icon.

Cursor

1. Install the server as above.

2. Create or edit .cursor/mcp.json in your project root:

3. Restart Cursor. The MCP tools will be available in the UI.

Example Usage

• Ask Claude or Cursor: "Run this JavaScript: 1 + 2"

• Use heap snapshots to persist state between runs.

Heap Storage Options

You can configure heap storage using the following command line arguments:

• S3: --s3-bucket <bucket>

  • Example: mcp-v8 --s3-bucket my-bucket-name

  • Requires AWS credentials in your environment.

• Filesystem: --directory-path <path>

  • Example: mcp-v8 --directory-path /tmp/mcp-v8-heaps

Note: Only one storage backend can be used at a time. If both are provided, the server will return an error.

Limitations

While mcp-v8 provides a powerful and persistent JavaScript execution environment, there are limitations to its runtime.

• No : Asynchronous JavaScript is not supported. All code must be synchronous.

• No : There is no built-in way to make HTTP requests or access the network.

• No : Output from console.log or similar functions will not appear. To return results, ensure the value you want is the last line of your code.

• No file system access: The runtime does not provide access to the local file system or environment variables.

• No : You cannot install or import npm packages. Only standard JavaScript (ECMAScript) built-ins are available.

• No timers: Functions like setTimeout and setInterval are not available.

• No DOM or browser APIs: This is not a browser environment; there is no access to window, document, or other browser-specific objects.

Build from Source (Advanced)

If you prefer to build from source instead of using the install script:

Prerequisites

• Rust (nightly toolchain recommended)

• (Optional) AWS credentials for S3 storage

Build the Server

The built binary will be located at server/target/release/server. You can use this path in the integration steps above instead of /usr/local/bin/mcp-v8 if desired.