NodeRun MCP Server

Official Model Context Protocol (MCP) server for NodeRun - Execute code on a distributed network with a single line of setup. Perfect for Claude, LangChain, and any MCP-compatible client.

Features

• Distributed Code Execution: Run Python, Node.js, TypeScript, Go, and Shell code in secure sandboxes
• Web Scraping: Fetch and scrape webpages with residential IP support to bypass rate limiting
• Regional Deployment: Execute code in specific regions (us-east, us-west, eu, asia) for optimized latency
• Easy Integration: Works with Claude Desktop, LangChain, and any MCP client
• Production Ready: Full error handling, retry logic, and comprehensive logging
• Affordable Pricing: Only $0.001 per API call

Quick Start

Prerequisites

• Node.js 18 or higher
• NodeRun API key (get one at noderun.dev)

Installation

npm install -g @noderun/mcp-server

Or use it directly with npx:

npx @noderun/mcp-server --api-key nr_your_api_key_here

Setup

Claude Desktop

1. Get your API key from noderun.dev/dashboard

2. Add NodeRun to your Claude Desktop configuration:

On macOS/Linux: Edit ~/.config/Claude/claude_desktop_config.json

On Windows: Edit %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "noderun": {
      "command": "npx",
      "args": ["@noderun/mcp-server", "--api-key", "nr_your_api_key_here"]
    }
  }
}

3. Restart Claude Desktop

4. You'll now see NodeRun tools available in Claude's tool list

LangChain

from langchain.agents import initialize_agent, Tool
import subprocess
import json

# Start the MCP server
process = subprocess.Popen(
    ["npx", "@noderun/mcp-server", "--api-key", "nr_your_api_key_here"],
    stdout=subprocess.PIPE,
    stderr=subprocess.PIPE
)

# Use with LangChain tools
from langchain_core.tools import Tool

noderun_tools = [
    Tool(
        name="run_code",
        func=lambda code, language="python": run_noderun_code(code, language),
        description="Execute code on NodeRun distributed network"
    ),
    Tool(
        name="web_scrape",
        func=lambda url: scrape_with_noderun(url),
        description="Scrape webpages using residential IPs"
    )
]

Node.js / JavaScript

import { NodeRunMCPServer } from '@noderun/mcp-server';

const server = new NodeRunMCPServer({
  apiKey: 'nr_your_api_key_here',
  baseUrl: 'https://api.noderun.dev', // optional
  timeout: 300000, // optional, in milliseconds
});

await server.start();

Available Tools

1. run_code

Execute code in a secure sandbox environment.

Parameters:

• language (required): python, nodejs, typescript, go, or shell
• code (required): Source code to execute
• timeout (optional): Execution timeout in seconds (default: 60, max: 300)
• dependencies (optional): Array of package names to install
• enable_network (optional): Allow network access (default: false)

Example with Claude:

Execute this Python code on NodeRun:
import json
data = {"status": "success", "message": "Hello from NodeRun"}
print(json.dumps(data, indent=2))

Example with LangChain:

result = await agent.run(
    "Run Python code to fetch and parse JSON from a public API"
)

2. web_scrape

Fetch and scrape webpage content using residential IPs to avoid rate limiting and blocks.

Parameters:

• url (required): Website URL to fetch

Example with Claude:

Scrape the content from https://example.com and extract all the main headings

Use Cases:

• Bypassing basic rate limiting
• Collecting data from websites with IP-based blocking
• Extracting structured data from HTML

3. distributed_execute

Execute code on NodeRun's distributed network with optional region selection for optimal performance.

Parameters:

• language (required): python, nodejs, typescript, go, or shell
• code (required): Source code to execute
• region (optional): Target region - us-east, us-west, eu, asia, or auto (default)
• timeout (optional): Execution timeout in seconds (default: 60, max: 300)
• dependencies (optional): Array of package names to install
• enable_network (optional): Allow network access (default: false)

Example with Claude:

Execute this Go program in the EU region to measure latency:
package main
import (
    "fmt"
    "time"
)
func main() {
    start := time.Now()
    // Your code here
    fmt.Printf("Execution time: %v\n", time.Since(start))
}

Usage Examples

Execute Python Code

Run this Python code:
import requests
response = requests.get('https://api.example.com/data')
print(response.json())

Data Analysis with Dependencies

Execute this Python code with numpy and pandas installed:
import pandas as pd
import numpy as np

data = {
    'values': [1, 2, 3, 4, 5],
    'names': ['A', 'B', 'C', 'D', 'E']
}
df = pd.DataFrame(data)
print(df.describe())

Node.js with NPM Packages

Execute this Node.js code with lodash and axios:
const _ = require('lodash');
const axios = require('axios');

async function fetchData() {
    const response = await axios.get('https://api.github.com/repos/nodejs/node');
    return _.pick(response.data, ['name', 'stars', 'forks']);
}

fetchData().then(console.log);

Web Scraping

Scrape https://news.ycombinator.com and extract the top 5 stories with their scores

Network-Enabled Code

Execute this code with network access enabled:
import socket
hostname = socket.gethostname()
ip = socket.gethostbyname(hostname)
print(f"Hostname: {hostname}")
print(f"IP: {ip}")

Regional Deployment

Execute this benchmark code in the Asia region:
import time
import hashlib

start = time.time()
for i in range(1000000):
    hashlib.sha256(str(i).encode()).hexdigest()
print(f"Time: {time.time() - start}s")

Configuration

Environment Variables

# API Key
export NODERUN_API_KEY=nr_your_api_key_here

# API Base URL (optional)
export NODERUN_BASE_URL=https://api.noderun.dev

# Request timeout in milliseconds (optional)
export NODERUN_TIMEOUT=300000

# Start the server
npx @noderun/mcp-server

Command Line Arguments

npx @noderun/mcp-server \
  --api-key nr_your_api_key_here \
  --base-url https://api.noderun.dev \
  --timeout 300000

Programmatic Configuration

import { NodeRunMCPServer } from '@noderun/mcp-server';

const config = {
  apiKey: process.env.NODERUN_API_KEY,
  baseUrl: 'https://api.noderun.dev', // Default
  timeout: 300000, // Default (5 minutes)
};

const server = new NodeRunMCPServer(config);
await server.start();

Pricing

NodeRun MCP Server has simple, transparent pricing:

• Per API Call: $0.001 (1/10 of a cent)
• Free Tier: 100 calls/month to test
• No Subscription Required: Pay only for what you use
• Volume Discounts: Available for high-volume users

Cost Examples

| Usage | Monthly Cost | |-------|--------------| | 1,000 calls | $1.00 | | 10,000 calls | $10.00 | | 100,000 calls | $100.00 | | 1,000,000 calls | $1,000.00 |

Check Your Account Balance

Use the NodeRun API to check your current balance and usage

View your detailed usage and billing at noderun.dev/dashboard.

API Key Management

Your API key is sensitive - keep it secure:

1. Generate Keys: Create API keys at noderun.dev/dashboard
2. Key Format: All keys start with nr_ followed by random characters
3. Rotation: Rotate keys regularly for security
4. Environment Variables: Store keys in .env files or environment variables, never in version control
5. Revocation: Revoke compromised keys immediately in the dashboard

Error Handling

The server includes comprehensive error handling:

• Automatic Retries: Transient errors are automatically retried with exponential backoff
• Timeouts: Requests timeout after 5 minutes by default (configurable)
• Rate Limiting: Respects API rate limits with smart retry strategies
• Validation: Input validation before sending to the API

Common Error Messages

| Error | Cause | Solution | |-------|-------|----------| | Invalid API key format | Key doesn't start with nr_ | Get a new key from the dashboard | | API request timeout | Task took too long | Increase timeout or optimize code | | Code execution failed | Runtime error in code | Check code syntax and dependencies | | Task did not complete | Service unavailable | Retry or check noderun.dev status |

Building from Source

git clone https://github.com/noderun-ai/noderun-mcp-server.git
cd noderun-mcp-server
npm install
npm run build

# Test locally
export NODERUN_API_KEY=nr_your_test_key
node dist/cli.js

Development

Project Structure

noderun-mcp-server/
├── src/
│   ├── index.ts          # Main MCP server implementation
│   ├── cli.ts            # CLI entry point
│   ├── client.ts         # NodeRun API client
│   ├── tools.ts          # Tool definitions and handlers
│   └── types.ts          # TypeScript type definitions
├── bin/
│   └── noderun-mcp.js    # Executable wrapper
├── dist/                 # Compiled JavaScript (generated)
├── package.json
├── tsconfig.json
└── README.md

Scripts

# Build TypeScript to JavaScript
npm run build

# Watch mode for development
npm run dev

# Prepare for publishing
npm run prepublishOnly

Troubleshooting

Server won't start

1. Check your API key: echo $NODERUN_API_KEY
2. Verify key format: Must start with nr_
3. Check internet connection
4. Try explicitly passing the key: noderun-mcp --api-key nr_xxx

Tools not appearing in Claude

1. Verify the MCP server started without errors
2. Check Claude Desktop configuration file syntax (valid JSON)
3. Restart Claude Desktop completely
4. Check the MCP server logs for errors

Code execution times out

1. Increase the timeout: --timeout 600000 (10 minutes)
2. Optimize your code to run faster
3. Check if external API calls are slow

Network errors

1. Verify internet connectivity
2. Check if the NodeRun API is accessible: curl https://api.noderun.dev/health
3. Check your firewall/proxy settings
4. Verify API key is valid at noderun.dev/dashboard

Supported Languages & Versions

• Python: 3.8, 3.9, 3.10, 3.11, 3.12
• Node.js: 16, 18, 20, 21
• TypeScript: 4.x, 5.x (compiled to Node.js)
• Go: 1.20, 1.21
• Shell: Bash 5.x, Sh

Popular packages are pre-installed in the sandbox. Install additional packages via the dependencies parameter.

Security

• All code runs in isolated sandboxes with no access to the host system
• Network access is disabled by default (opt-in via enable_network)
• Execution timeout enforces 5-minute maximum runtime
• API keys are encrypted in transit and at rest
• No code is logged or stored permanently

Contributing

We welcome contributions! Please see our Contributing Guide.

Support

• Documentation: noderun.dev/docs
• Dashboard: noderun.dev/dashboard
• Status Page: status.noderun.dev
• Email: [email protected]
• GitHub Issues: noderun-ai/noderun-mcp-server/issues

License

MIT © NodeRun

Related Resources

• Model Context Protocol
• Claude Desktop Setup
• LangChain Integration
• NodeRun Homepage

Ready to execute code globally? Sign up for NodeRun and get your API key today.