Orgo MCP Server
An MCP (Model Context Protocol) server that gives AI agents the ability to control virtual computers through Orgo.
Get Started in 60 Seconds
+-------------------------------------------------------------+
| STEP 1: Get Key > STEP 2: Configure > STEP 3: Use! |
+-------------------------------------------------------------+
Step 1: Get Your API Key
| Action | Link |
|---|---|
| New user? | Sign up at orgo.ai |
| Existing user? | Go to Dashboard |
Where to find your key:
+----------------------------------------------------------+
| orgo.ai Dashboard |
+----------------------------------------------------------+
| |
| Settings > API Keys > [ Copy Key ] |
| |
| Your key looks like: sk_live_abc123... |
| ^^^^^^^^ |
| Always starts with sk_live_ |
| |
+----------------------------------------------------------+
Tip: Keep your API key private - never commit it to git!
Step 2: Configure Your Client
Choose your setup method:
Claude Code (CLI) - Recommended
Run this single command:
claude mcp add --transport http orgo https://orgo-mcp.onrender.com/mcp \
--header "X-Orgo-API-Key: YOUR_API_KEY"
# ^^^^^^^^^^^^^
# Replace this with your actual key!
Example with a real key format:
claude mcp add --transport http orgo https://orgo-mcp.onrender.com/mcp \
--header "X-Orgo-API-Key: sk_live_abc123xyz789"
Claude Desktop (macOS)
1. Open your config file:
open ~/Library/Application\ Support/Claude/claude_desktop_config.json
2. Add this configuration:
{
"mcpServers": {
"orgo": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://orgo-mcp.onrender.com/mcp",
"--header", "X-Orgo-API-Key:sk_live_YOUR_KEY_HERE"]
}
}
}
Important: No space after the colon in
X-Orgo-API-Key:sk_live_...
3. Restart Claude Desktop
Claude Desktop (Windows)
1. Open your config file:
%APPDATA%\Claude\claude_desktop_config.json
2. Add this configuration:
{
"mcpServers": {
"orgo": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://orgo-mcp.onrender.com/mcp",
"--header", "X-Orgo-API-Key:sk_live_YOUR_KEY_HERE"]
}
}
}
Important: No space after the colon in
X-Orgo-API-Key:sk_live_...
3. Restart Claude Desktop
Team Project (.mcp.json)
For sharing with your team without exposing keys:
1. Create .mcp.json in your project root:
{
"mcpServers": {
"orgo": {
"type": "http",
"url": "https://orgo-mcp.onrender.com/mcp",
"headers": {
"X-Orgo-API-Key": "${ORGO_API_KEY}"
}
}
}
}
2. Each team member sets their own key:
# Add to ~/.bashrc or ~/.zshrc for persistence
export ORGO_API_KEY="sk_live_your_personal_key"
Step 3: Start Using!
Try these commands in Claude:
"Create a Linux computer with 4GB RAM"
"Take a screenshot of my computer"
"Run 'ls -la' on the computer"
"Type 'hello world' and press Enter"
Troubleshooting API Key Issues
Common Problems and Quick Fixes
| Error Message | What is Wrong | How to Fix |
|---|---|---|
Invalid API key | Key format is wrong | Make sure it starts with sk_live_ |
X-Orgo-API-Key header required | Key not passed correctly | Check for extra spaces in header |
401 Unauthorized | Key is expired or invalid | Generate a new key at orgo.ai |
Quick validation checklist:
[ ] Key starts with: sk_live_
[ ] No extra spaces before/after the key
[ ] Key copied completely (no truncation)
[ ] Quotes are straight " not curly
Features (34 tools)
| Category | Tools |
|---|---|
| Projects | orgo_list_projects, orgo_create_project, orgo_get_project, orgo_delete_project, orgo_start_project, orgo_stop_project, orgo_restart_project |
| Computers | orgo_list_computers, orgo_create_computer, orgo_get_computer, orgo_start_computer, orgo_stop_computer, orgo_restart_computer, orgo_delete_computer |
| Actions | orgo_screenshot, orgo_click, orgo_double_click, orgo_type, orgo_key, orgo_scroll, orgo_drag, orgo_wait |
| Shell | orgo_bash, orgo_exec |
| Files | orgo_list_files, orgo_upload_file, orgo_export_file, orgo_download_file, orgo_delete_file |
| Streaming | orgo_start_stream, orgo_stream_status, orgo_stop_stream |
| AI | orgo_list_ai_models, orgo_ai_completion |
Self-Hosting Options
Option 1: Local Development (stdio)
git clone https://github.com/nickvasilescu/orgo-mcp.git
cd orgo-mcp
pip install -e .
export ORGO_API_KEY="your_key"
python orgo_mcp.py
Add to claude_desktop_config.json:
{
"mcpServers": {
"orgo": {
"command": "python3",
"args": ["/path/to/orgo-mcp/orgo_mcp.py"],
"env": {"ORGO_API_KEY": "your_key"}
}
}
}
Option 2: Local HTTP Server
pip install -e .
MCP_TRANSPORT=http python orgo_mcp.py
Server available at http://localhost:8000/mcp
Option 3: Docker
# Build
docker build -t orgo-mcp .
# Run
docker run -p 8000:8000 orgo-mcp
# Or use docker-compose
docker-compose up
Option 4: Deploy to Render.com
- Fork this repository
- Go to Render Dashboard
- Click "New Blueprint Instance"
- Connect your GitHub repo
- Deploy!
Your server will be at: https://orgo-mcp-xxxx.onrender.com
Option 5: Deploy to Fly.io
# Install flyctl
curl -L https://fly.io/install.sh | sh
# Login and deploy
fly auth login
fly launch --no-deploy
fly deploy
Your server will be at: https://orgo-mcp.fly.dev
Environment Variables
| Variable | Default | Description |
|---|---|---|
MCP_TRANSPORT | stdio | Transport mode: stdio or http |
MCP_HOST | 0.0.0.0 | HTTP bind address |
MCP_PORT / PORT | 8000 | HTTP port |
ORGO_API_KEY | - | API key (required for stdio transport) |
CORS_ORIGINS | * | Allowed origins (comma-separated) |
Usage Examples
Project Management
"Create a new project called 'qa-automation'"
"List my Orgo projects"
"Start all computers in project proj_123"
"Delete project proj_123"
Computer Management
"Create a new Linux computer called 'dev-box' with 4GB RAM"
"Get details for computer abc123"
"Start computer abc123"
"Stop computer abc123"
Screen Actions
"Take a screenshot of computer abc123"
"Click at coordinates (500, 300)"
"Type 'hello world'"
"Press Enter"
"Scroll down"
Shell Commands
"Run 'ls -la' on computer abc123"
"Execute Python code: print('hello')"
File Operations
"List files on computer abc123"
"Export file ~/Documents/report.pdf from computer abc123"
"Upload file to computer abc123"
Streaming
"Start streaming computer abc123 to Twitch"
"Check stream status for computer abc123"
"Stop streaming computer abc123"
AI Completion
"List available AI models"
"Run GPT-4 completion: 'Explain quantum computing'"
Additional Troubleshooting
"Connection refused" Error
- Cloud: Check
https://orgo-mcp.onrender.com/health - Local: Ensure server is running on correct port
- Check firewall/proxy settings
Claude Desktop Not Connecting
- Restart Claude Desktop after config changes
- Check config file syntax (valid JSON)
- View logs: Help > Troubleshooting > Open Logs
Tools Not Appearing
- Wait 10-30 seconds after connection
- Check server logs for errors
- Verify MCP server is listed in Claude settings
Architecture
Cloud Deployment:
Client (Claude) --> HTTPS --> Cloud Server --> Orgo API
X-Orgo-API-Key header
Local Deployment:
Client (Claude) --> stdio --> orgo_mcp.py --> Orgo API
ORGO_API_KEY env var
Project Structure
orgo-mcp/
+-- orgo_mcp.py # MCP server (34 tools, dual transport)
+-- pyproject.toml # Package configuration
+-- Dockerfile # Production container
+-- docker-compose.yml # Local development
+-- render.yaml # Render.com deployment
+-- fly.toml # Fly.io deployment
+-- .dockerignore # Docker build exclusions
+-- .env.example # Environment template
+-- README.md
+-- LICENSE
Development
# Install dev dependencies
pip install -e ".[dev]"
# Format code
black orgo_mcp.py
# Lint
ruff check orgo_mcp.py
# Run tests
pytest
# Test HTTP transport locally
MCP_TRANSPORT=http python orgo_mcp.py
# Test health endpoint
curl http://localhost:8000/health
# Test MCP endpoint
curl -X POST http://localhost:8000/mcp \
-H "Content-Type: application/json" \
-H "X-Orgo-API-Key: your_key" \
-d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
License
MIT License - see LICENSE