Replit Server

A production-ready Model Context Protocol (MCP) server for coding workflows on Replit. Designed for seamless integration with Claude Desktop and other MCP-compatible coding agents.

Features

• File Management — Read, write, delete, move, list, and search files recursively
• Code Execution — Sandboxed execution for Node.js, Python, and Bash with timeout controls
• Terminal Sessions — Persistent terminal session management with safety controls
• Git Integration — Status, log, diff, commit, and branch management
• Package Management — Install/uninstall npm, pip, and yarn packages
• Environment Variables — Secure storage with optional value redaction
• API Key Authentication — Create, revoke, and manage API keys with per-key permissions
• Rate Limiting — Per-IP and per-key rate limiting with configurable windows
• Audit Logging — Full request audit trail with tool name, level, and metadata
• WebSocket Streaming — Real-time output streaming for long-running executions
• Monitoring Dashboard — Live metrics, connection tracking, and tool usage stats
• MCP Protocol — Claude Desktop compatible /api/mcp/tools manifest and tool call endpoint

Quick Start

On Replit

The server starts automatically. Access the dashboard at your Replit preview URL.

Local with Docker

git clone <your-repo>
cd <your-repo>

# Start database and API server
docker-compose up -d

# The API is now available at http://localhost:5000

Local without Docker

# Install dependencies
pnpm install

# Set required environment variables
export DATABASE_URL="postgresql://user:password@localhost:5432/mcpserver"
export PORT=5000

# Push database schema
pnpm --filter @workspace/db run push

# Start the API server
pnpm --filter @workspace/api-server run dev

Claude Desktop Configuration

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "replit-mcp": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/client-http"],
      "env": {
        "MCP_SERVER_URL": "https://your-replit-url.replit.app/api/mcp",
        "MCP_API_KEY": "mcp_your_api_key_here"
      }
    }
  }
}

Or use the SSE transport directly:

{
  "mcpServers": {
    "replit-mcp": {
      "url": "https://your-replit-url.replit.app/api/mcp/tools",
      "headers": {
        "X-API-Key": "mcp_your_api_key_here"
      }
    }
  }
}

API Reference

Authentication

All endpoints accept an API key via:

• X-API-Key: mcp_your_key header
• Authorization: Bearer mcp_your_key header

Create your first API key (no auth required for initial setup):

curl -X POST http://localhost:5000/api/auth/keys \
  -H "Content-Type: application/json" \
  -d '{"name": "My Agent", "permissions": ["read", "write", "execute"]}'

File Operations

# List files
curl "http://localhost:5000/api/files?path=.&recursive=true"

# Read file
curl "http://localhost:5000/api/files/read?path=src/index.ts"

# Write file
curl -X POST http://localhost:5000/api/files/write \
  -H "Content-Type: application/json" \
  -d '{"path": "hello.js", "content": "console.log(\"hello\")"}'

# Search files
curl "http://localhost:5000/api/files/search?query=TODO&filePattern=*.ts"

# Delete file
curl -X DELETE "http://localhost:5000/api/files/delete?path=hello.js"

Code Execution

# Run Node.js
curl -X POST http://localhost:5000/api/execute \
  -H "Content-Type: application/json" \
  -d '{"language": "node", "code": "console.log(2 + 2)", "timeout": 10}'

# Run Python
curl -X POST http://localhost:5000/api/execute \
  -H "Content-Type: application/json" \
  -d '{"language": "python", "code": "print(\"hello from python\")", "timeout": 10}'

# Run Bash
curl -X POST http://localhost:5000/api/execute \
  -H "Content-Type: application/json" \
  -d '{"language": "bash", "code": "ls -la && echo done", "timeout": 10}'

Git

# Get status
curl http://localhost:5000/api/git/status

# View commit log
curl "http://localhost:5000/api/git/log?limit=10"

# Commit changes
curl -X POST http://localhost:5000/api/git/commit \
  -H "Content-Type: application/json" \
  -d '{"message": "feat: add new feature", "all": true}'

MCP Protocol

# Get tools manifest (for Claude Desktop)
curl http://localhost:5000/api/mcp/tools

# Call a tool
curl -X POST http://localhost:5000/api/mcp/tools/call \
  -H "Content-Type: application/json" \
  -d '{"name": "read_file", "arguments": {"path": "README.md"}}'

Monitoring

# Server stats
curl http://localhost:5000/api/monitoring/stats

# Active connections
curl http://localhost:5000/api/monitoring/connections

# Rate limit status
curl http://localhost:5000/api/monitoring/rate-limits

# All MCP tools with usage
curl http://localhost:5000/api/monitoring/tools

MCP Tools Available

Tool	Category	Description
read_file	files	Read file contents
write_file	files	Write or overwrite a file
delete_file	files	Delete a file or directory
list_files	files	List directory contents
search_files	files	Recursive content search
move_file	files	Move or rename a file
execute_node	execution	Run Node.js code
execute_python	execution	Run Python code
execute_bash	execution	Run Bash script
run_terminal	terminal	Execute shell command
git_status	git	Repository status
git_commit	git	Stage and commit changes
git_diff	git	View code diff
git_log	git	Commit history
install_package	packages	Install npm/pip package
list_packages	packages	List installed packages
get_env	environment	List env variable keys
set_env	environment	Set env variable

Environment Variables

Variable	Required	Default	Description
DATABASE_URL	Yes	—	PostgreSQL connection string
PORT	Yes	5000	Server port
NODE_ENV	No	development	Environment
WORK_DIR	No	cwd	Base directory for file ops
SESSION_SECRET	No	—	Session signing secret
LOG_LEVEL	No	info	Logging level

Safety Controls

The server implements several safety controls for code execution:

• Blocked patterns: rm -rf /, shutdown, reboot, mkfs, dd if=, fork bombs
• Execution timeout: All code execution has a configurable timeout (default 30s)
• Path traversal protection: File operations are sandboxed to WORK_DIR
• Rate limiting: 200 requests per minute per IP by default
• Output size limit: 1MB stdout/stderr buffer

WebSocket Streaming

Connect to /ws for real-time execution output streaming:

const ws = new WebSocket("wss://your-server.replit.app/ws");
ws.send(JSON.stringify({
  type: "execute",
  language: "bash",
  code: "for i in $(seq 1 10); do echo $i; sleep 0.5; done"
}));
ws.onmessage = (e) => console.log(JSON.parse(e.data));

Example Client Configurations

Python Client

import requests

BASE_URL = "http://localhost:5000/api"
API_KEY = "mcp_your_key_here"
HEADERS = {"X-API-Key": API_KEY, "Content-Type": "application/json"}

def read_file(path):
    r = requests.get(f"{BASE_URL}/files/read", params={"path": path}, headers=HEADERS)
    return r.json()["content"]

def run_python(code, timeout=30):
    r = requests.post(f"{BASE_URL}/execute", json={"language": "python", "code": code, "timeout": timeout}, headers=HEADERS)
    return r.json()

def git_status():
    r = requests.get(f"{BASE_URL}/git/status", headers=HEADERS)
    return r.json()

JavaScript/TypeScript Client

const BASE_URL = "http://localhost:5000/api";
const API_KEY = "mcp_your_key_here";

const headers = {
  "X-API-Key": API_KEY,
  "Content-Type": "application/json",
};

const mcp = {
  readFile: (path: string) =>
    fetch(`${BASE_URL}/files/read?path=${encodeURIComponent(path)}`, { headers }).then(r => r.json()),

  executeCode: (language: "node" | "python" | "bash", code: string) =>
    fetch(`${BASE_URL}/execute`, {
      method: "POST",
      headers,
      body: JSON.stringify({ language, code }),
    }).then(r => r.json()),

  callTool: (name: string, args: Record<string, unknown>) =>
    fetch(`${BASE_URL}/mcp/tools/call`, {
      method: "POST",
      headers,
      body: JSON.stringify({ name, arguments: args }),
    }).then(r => r.json()),
};

License

MIT