npm package: @javaguru/server-judge0
Description: MCP server for executing code in 70+ programming languages using Judge0 CE API
Author: javaguru
Latest version: 1.1.0

# Judge0 MCP Server

> Execute code in **70+ programming languages** via Model Context Protocol (MCP)

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org/)
[![MCP](https://img.shields.io/badge/MCP-Compatible-blue)](https://modelcontextprotocol.io/)

A production-ready MCP server that provides secure code execution capabilities using the [Judge0 CE API](https://ce.judge0.com/). Perfect for AI agents, chatbots, and any application needing sandboxed code execution.

---

## ✨ Features

- 🚀 **70+ Programming Languages** - Python, JavaScript, Java, C++, Go, Rust, PHP, Ruby, and more
- 🔒 **Secure Sandboxed Execution** - Isolated containers with resource limits
- ⚡ **Auto Language Detection** - Automatically identifies programming language from code
- 📊 **Performance Metrics** - Execution time and memory usage tracking
- 🆓 **FREE Tier Available** - 50 executions/day via RapidAPI
- 🏠 **Self-Hosting Support** - Unlimited FREE usage with your own Judge0 instance
- 🛠️ **4 MCP Tools** - Flexible execution options
- 📖 **Comprehensive Documentation** - Guides, examples, and troubleshooting

---

## 🚀 Quick Start

### Prerequisites

- Node.js 18+ installed
- Judge0 API key from [RapidAPI](https://rapidapi.com/judge0-official/api/judge0-ce) (FREE tier available)

### Installation

**Option 1: Using npx (Recommended)**

No installation needed! Just configure your MCP client to use:

```bash
npx -y @javaguru/server-judge0
```

**Option 2: Local Installation**

```bash
# Clone the repository
git clone https://github.com/YOUR_USERNAME/judge0-mcp-server.git
cd judge0-mcp-server

# Install dependencies
npm install

# Configure environment (if using locally)
cp .env.example .env
# Edit .env and add your RAPIDAPI_KEY
```

---

## 📦 Package Information

**Package Name:** `@javaguru/server-judge0`

This package uses modern npm **scoped naming** (the `@javaguru/` prefix), following the pattern established by official MCP servers like `@modelcontextprotocol/server-filesystem`.

**Benefits:**
- ✅ Modern scoped package naming following MCP ecosystem conventions
- ✅ Easy to install with `npx -y @javaguru/server-judge0`
- ✅ Platform-agnostic - works with all MCP-compatible clients
- ✅ Clear ownership under the `@javaguru` scope

---

## ⚙️ Configuration

### Claude Desktop

Edit your Claude Desktop configuration file:

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

**macOS/Linux:**
```json
{
  "mcpServers": {
    "judge0": {
      "command": "npx",
      "args": [
        "-y",
        "@javaguru/server-judge0"
      ],
      "env": {
        "RAPIDAPI_KEY": "your_rapidapi_key_here"
      }
    }
  }
}
```

**Windows:**
```json
{
  "mcpServers": {
    "judge0": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@javaguru/server-judge0"
      ],
      "env": {
        "RAPIDAPI_KEY": "your_rapidapi_key_here"
      }
    }
  }
}
```

### ChatBox

Edit your ChatBox MCP configuration file:

**macOS:** `~/Library/Application Support/ChatMcp/mcp_server.json`
**Linux:** `~/.local/share/ChatMcp/mcp_server.json`
**Windows:** `%APPDATA%\ChatMcp\mcp_server.json`

**macOS/Linux:**
```json
{
  "mcpServers": {
    "judge0": {
      "command": "npx",
      "args": [
        "-y",
        "@javaguru/server-judge0"
      ],
      "env": {
        "RAPIDAPI_KEY": "your_rapidapi_key_here"
      }
    }
  }
}
```

**Windows:**
```json
{
  "mcpServers": {
    "judge0": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@javaguru/server-judge0"
      ],
      "env": {
        "RAPIDAPI_KEY": "your_rapidapi_key_here"
      }
    }
  }
}
```

### Jan AI

**GUI Configuration:**

1. Open Jan AI and go to **Settings** > **Advanced**
2. Enable **"Allow All MCP Tool Permission"**
3. Go to **Settings** > **MCP Servers**
4. Click the **+** icon to add a new server
5. Enter the following:

   **macOS/Linux:**
   - **Server Name:** `judge0`
   - **Command:** `npx`
   - **Args:** `-y @javaguru/server-judge0`
   - **Environment Variables:**
     - Key: `RAPIDAPI_KEY`
     - Value: `your_rapidapi_key_here`

   **Windows:**
   - **Server Name:** `judge0`
   - **Command:** `cmd`
   - **Args:** `/c npx -y @javaguru/server-judge0`
   - **Environment Variables:**
     - Key: `RAPIDAPI_KEY`
     - Value: `your_rapidapi_key_here`

**Or edit Jan's configuration file directly:**

**macOS/Linux:**
```json
{
  "mcpServers": {
    "judge0": {
      "command": "npx",
      "args": [
        "-y",
        "@javaguru/server-judge0"
      ],
      "env": {
        "RAPIDAPI_KEY": "your_rapidapi_key_here"
      }
    }
  }
}
```

**Windows:**
```json
{
  "mcpServers": {
    "judge0": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@javaguru/server-judge0"
      ],
      "env": {
        "RAPIDAPI_KEY": "your_rapidapi_key_here"
      }
    }
  }
}
```

### LibreChat

Add to your `librechat.yaml` configuration file:

```yaml
version: 1.1.5
cache: true

mcpServers:
  judge0:
    type: stdio
    command: npx
    args:
      - -y
      - "@javaguru/server-judge0"
    env:
      RAPIDAPI_KEY: "${RAPIDAPI_KEY}"
    timeout: 30000
    initTimeout: 10000
    serverInstructions: "Execute code in 70+ programming languages securely"
```

**Environment Variables in `.env`:**
```bash
RAPIDAPI_KEY=your_rapidapi_key_here
```

**Important:** Restart LibreChat after configuration changes.

### Zed Editor

Create or edit `.zed/mcp.json` in your project:

**macOS/Linux:**
```json
{
  "mcpServers": {
    "judge0": {
      "command": "npx",
      "args": [
        "-y",
        "@javaguru/server-judge0"
      ],
      "env": {
        "RAPIDAPI_KEY": "your_rapidapi_key_here"
      }
    }
  }
}
```

**Windows:**
```json
{
  "mcpServers": {
    "judge0": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@javaguru/server-judge0"
      ],
      "env": {
        "RAPIDAPI_KEY": "your_rapidapi_key_here"
      }
    }
  }
}
```

### VS Code

Open Command Palette (`Ctrl+Shift+P`) → Run **"MCP: Open User Configuration"** or edit `.vscode/mcp.json`:

**macOS/Linux:**
```json
{
  "mcpServers": {
    "judge0": {
      "command": "npx",
      "args": [
        "-y",
        "@javaguru/server-judge0"
      ],
      "env": {
        "RAPIDAPI_KEY": "your_rapidapi_key_here"
      }
    }
  }
}
```

**Windows:**
```json
{
  "mcpServers": {
    "judge0": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@javaguru/server-judge0"
      ],
      "env": {
        "RAPIDAPI_KEY": "your_rapidapi_key_here"
      }
    }
  }
}
```

### Local Development (Without npx)

If you cloned the repository locally:

```json
{
  "mcpServers": {
    "judge0": {
      "command": "node",
      "args": [
        "/absolute/path/to/judge0-mcp-server/index.js"
      ],
      "env": {
        "RAPIDAPI_KEY": "your_rapidapi_key_here"
      }
    }
  }
}
```

**Note:** Always use absolute paths in configuration files.

---

## 🛠️ Available Tools

### 1. `execute_code`

Main execution tool with automatic language detection.

**Parameters:**
- `code` (string, required) - Source code to execute
- `language` (string, optional) - Programming language (auto-detected if not specified)
- `stdin` (string, optional) - Standard input for the program
- `timeout` (number, optional) - CPU time limit in seconds (max 15)

**Example:**
```json
{
  "code": "print('Hello, World!')",
  "language": "python"
}
```

**Response:**
```
✅ Execution Successful

Language: Python

Output:
Hello, World!

Performance:
- Execution time: 0.023s
- Memory used: 3.2 MB
```

### 2. `execute_python`

Convenient shortcut for Python execution.

**Parameters:**
- `code` (string, required) - Python code
- `stdin` (string, optional) - Standard input

### 3. `execute_javascript`

Convenient shortcut for JavaScript (Node.js) execution.

**Parameters:**
- `code` (string, required) - JavaScript code
- `stdin` (string, optional) - Standard input

### 4. `list_languages`

Discover all supported programming languages.

**Parameters:** None

**Returns:** Complete list of 70+ languages with their aliases and IDs

---

## 📚 Supported Languages

### Popular Languages (19)
Python 3, JavaScript (Node.js), TypeScript, Java, C, C++, C#, Go, Rust, PHP, Ruby, Swift, Kotlin, R, Bash, SQL, Perl, Scala, Groovy

### Functional Languages (7)
Haskell, Clojure, Elixir, Erlang, OCaml, F#, Lisp

### And 40+ More!

Use the `list_languages` tool to see the complete list with all aliases.

---

## 💡 Usage Examples

### With LibreChat

Create an agent with Judge0 tools enabled:

**User:** "Write a Python function to calculate fibonacci numbers and run it with n=10"

**Agent:**
```python
def fibonacci(n):
    if n <= 1:
        return n
    a, b = 0, 1
    for _ in range(n - 1):
        a, b = b, a + b
    return b

result = fibonacci(10)
print(f"Fibonacci(10) = {result}")
```

[Executes via `execute_python` tool]

**Output:**
```
Fibonacci(10) = 55
```

### With Claude Desktop

Add to your MCP settings and use in conversations:

```
User: Can you run this JavaScript code?
const arr = [3, 1, 4, 1, 5, 9];
console.log('Sorted:', arr.sort((a, b) => a - b));
```

Claude will automatically use the Judge0 MCP server to execute the code.

### With Zed Editor

Configure in Zed's MCP settings to execute code snippets directly from your editor.

---

## 🔧 Environment Variables

The server supports two deployment modes:

### RapidAPI Mode (Default)

```json
{
  "env": {
    "RAPIDAPI_KEY": "your_rapidapi_key_here"
  }
}
```

- **FREE tier:** 50 executions/day
- **Paid plans:** Starting at $50/month for 30,000 executions
- Get your key: [RapidAPI Judge0](https://rapidapi.com/judge0-official/api/judge0-ce)

### Self-Hosted Mode (Unlimited FREE)

For unlimited usage, run your own Judge0 instance:

```bash
# Clone Judge0
git clone https://github.com/judge0/judge0.git
cd judge0

# Start with Docker Compose
docker-compose up -d

# API available at: http://localhost:2358
```

Then configure your MCP client:

**macOS/Linux:**
```json
{
  "mcpServers": {
    "judge0": {
      "command": "npx",
      "args": ["-y", "@javaguru/server-judge0"],
      "env": {
        "JUDGE0_BASE_URL": "http://localhost:2358"
      }
    }
  }
}
```

**Windows:**
```json
{
  "mcpServers": {
    "judge0": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@javaguru/server-judge0"],
      "env": {
        "JUDGE0_BASE_URL": "http://localhost:2358"
      }
    }
  }
}
```

**Note:** When using self-hosted, you don't need `RAPIDAPI_KEY`.

---

## 🔒 Security

### Sandboxing

All code execution happens in Judge0's secure sandbox:

- ✅ **Process Isolation** - Each execution in separate container
- ✅ **Resource Limits** - CPU time (max 15s), Memory (128MB default)
- ✅ **Network Restrictions** - No external network access
- ✅ **File System Isolation** - Limited sandbox directory
- ✅ **Automatic Cleanup** - Containers destroyed after execution

### Best Practices

1. Set appropriate timeouts for long-running code
2. Monitor usage via RapidAPI dashboard
3. Use self-hosted for sensitive code
4. Validate code before execution
5. Review execution results

---

## 💰 Pricing

### RapidAPI FREE Tier
- **50 executions/day**
- **No credit card required**
- Perfect for personal use and testing

### RapidAPI Paid Plans
- **$50/month**: 30,000 executions
- **Pay-as-you-go**: $5 per 1,000 executions

### Self-Hosted
- **FREE unlimited usage**
- Requires Docker infrastructure
- Full control and privacy

---

## 🧪 Testing

### Manual Test

```bash
# Set your API key
export RAPIDAPI_KEY="your_key_here"

# Run the server
npm start
```

**Expected output:**
```
Judge0 MCP Server starting...
✓ Connected to Judge0 API successfully
✓ Supports 70+ programming languages
✓ Ready to execute code via MCP
Judge0 MCP Server running
```

### Integration Test

Use with any MCP client to test code execution across different languages.

---

## 📖 Documentation

- **[Installation Guide](docs/installation.md)** - Detailed setup instructions
- **[API Reference](docs/api.md)** - Complete tool documentation
- **[Language Support](docs/languages.md)** - All 70+ languages with examples
- **[Troubleshooting](docs/troubleshooting.md)** - Common issues and solutions
- **[Self-Hosting Guide](docs/self-hosting.md)** - Run your own Judge0

---

## 🤝 Compatible MCP Clients

- ✅ **[Claude Desktop](https://claude.ai/desktop)** - Anthropic's desktop app
- ✅ **[ChatBox](https://chatboxai.app/)** - Multi-platform AI chat client
- ✅ **[Jan AI](https://jan.ai/)** - Open-source ChatGPT alternative
- ✅ **[LibreChat](https://librechat.ai/)** - Multi-model AI chat platform
- ✅ **[Zed](https://zed.dev/)** - High-performance code editor
- ✅ **[VS Code](https://code.visualstudio.com/)** - With MCP extension
- ✅ **Any MCP-compatible application**

---

## 🐛 Troubleshooting

### Cannot connect to Judge0 API

**Solution:**
1. Verify `RAPIDAPI_KEY` in `.env`
2. Check API key validity on RapidAPI dashboard
3. Ensure you're subscribed to Judge0 CE (FREE tier)

### Rate limit exceeded

**Solution:**
1. Wait 24 hours for limit reset
2. Upgrade to paid plan
3. Use self-hosted Judge0 (unlimited)

### Unknown language error

**Solution:**
- Use `list_languages` tool to see supported languages
- Check language name spelling
- Try common aliases (e.g., "py" for Python)

For more issues, see [Troubleshooting Guide](docs/troubleshooting.md)

---

## 🤝 Contributing

Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

### Ways to Contribute

- 🐛 Report bugs
- ✨ Suggest features
- 📖 Improve documentation
- 🌍 Add language support
- 🧪 Write tests
- 🔧 Fix issues

---

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

## 🙏 Acknowledgments

- **[Judge0](https://ce.judge0.com/)** - Excellent code execution platform
- **[Model Context Protocol](https://modelcontextprotocol.io/)** - Tool integration standard
- **[LibreChat](https://librechat.ai/)** - Inspiration and use case
- **Community Contributors** - Thank you!

---

## 📊 Stats

- **Languages Supported:** 70+
- **MCP Tools:** 4
- **Lines of Code:** ~1,500
- **Documentation:** Comprehensive
- **License:** MIT
- **Status:** Production Ready

---

## 🔗 Links

- **Repository:** https://github.com/YOUR_USERNAME/judge0-mcp-server
- **Issues:** https://github.com/YOUR_USERNAME/judge0-mcp-server/issues
- **Judge0 API:** https://ce.judge0.com/
- **RapidAPI:** https://rapidapi.com/judge0-official/api/judge0-ce
- **MCP Specification:** https://modelcontextprotocol.io/

---

## ⭐ Show Your Support

If you find this project useful, please consider:
- ⭐ Starring the repository
- 🐛 Reporting bugs
- 💡 Suggesting features
- 🤝 Contributing code
- 📢 Sharing with others

---

**Built with ❤️ for the MCP and AI community**

**Ready to execute code? Get started now!** 🚀