picoclaw-mcp-server

A Model Context Protocol (MCP) server with browser automation, GitHub integration, and persistent opencode repository support.

Features

Browser Automation

• Human-like behavior: Random delays, bezier-curve mouse movements, viewport/user-agent randomization
• Stealth mode: Avoids bot detection using playwright-stealth
• Full browser control: Navigate, click, type, scroll, hover, screenshot, get page content

GitHub Integration

• List repository files
• Read file contents
• Search code
• Search repositories
• Get repository information

OpenCode Integration (Persistent)

• Auto-clone/pull: Automatically clone or pull your opencode repository on startup
• Heartbeat refresh: Periodic automatic refresh (configurable interval)
• Manual refresh: MCP tools to force pull/refresh
• Local file access: Read, list, and search your opencode repository

Utilities

• Web search via DuckDuckGo
• URL fetching

Installation

# Clone the repository
git clone https://github.com/Evansxm/picoclaw-mcp-server.git
cd picoclaw-mcp-server

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Linux/Mac
# venv\Scripts\activate  # Windows

# Install dependencies
pip install -r requirements.txt

# Install Playwright browsers
playwright install chromium

Configuration

Environment Variables

Variable	Default	Description
GITHUB_TOKEN	-	GitHub Personal Access Token for higher rate limits
HEADLESS	true	Run browser in headless mode
STEALTH_MODE	true	Enable stealth mode to avoid bot detection
OPENCODE_ENABLED	true	Enable opencode repository integration
OPENCODE_REPO_URL	-	URL of your opencode repository
OPENCODE_LOCAL_PATH	~/opencode-clone	Local path to clone the repository
OPENCODE_REFRESH_INTERVAL	1800	Seconds between automatic refreshes

Configuration File

You can also configure via ~/.picoclaw/config.json:

{
  "opencode": {
    "enabled": true,
    "repo_url": "https://github.com/yourusername/your-opencode-repo",
    "local_path": "~/opencode-clone",
    "refresh_interval": 1800,
    "github_token": "your-github-token"
  }
}

Claude Desktop Configuration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "picoclaw": {
      "command": "/path/to/picoclaw-mcp-server/venv/bin/python",
      "args": ["/path/to/picoclaw-mcp-server/server.py"],
      "env": {
        "GITHUB_TOKEN": "your-github-token-here",
        "OPENCODE_ENABLED": "true",
        "OPENCODE_REPO_URL": "https://github.com/yourusername/your-repo",
        "HEADLESS": "false",
        "STEALTH_MODE": "true"
      }
    }
  }
}

Cursor Configuration

Add to Cursor settings (Settings → Tools → MCP):

{
  "mcpServers": {
    "picoclaw": {
      "command": "python",
      "args": ["/absolute/path/to/picoclaw-mcp-server/server.py"],
      "env": {
        "GITHUB_TOKEN": "your-github-token-here",
        "OPENCODE_ENABLED": "true"
      }
    }
  }
}

Available Tools

OpenCode Tools

Tool	Description
`opencode	Force pull/refresh the opencode repository
_pull_repoopencode_clone_repo`	Clone or ensure repository exists locally
opencode_list_files	List files in the opencode repository
opencode_read_file	Read a file from the opencode repository
opencode_search_code	Search for code in the opencode repository
opencode_get_status	Get status of the opencode repository

Browser Tools

Tool	Description
browser_navigate	Navigate to a URL
browser_click	Click element by CSS selector
browser_click_text	Click element by text content
browser_type	Type text into input
browser_scroll	Scroll the page
browser_screenshot	Take a screenshot
browser_get_screenshot_base64	Get screenshot as base64
browser_get_page_content	Get page text content
browser_get_page_html	Get page HTML source
browser_hover	Hover over element
browser_wait	Wait for seconds
browser_close	Close browser

GitHub Tools

Tool	Description
list_repo_files	List files in a repository
read_file	Read file contents
search_code	Search code on GitHub
search_repositories	Search repositories
get_repository_info	Get repository information

Utility Tools

Tool	Description
web_search	Search the web via DuckDuckGo
fetch_url	Fetch URL content

Systemd Service (Always-On)

For persistent always-on behavior on Linux:

# Copy the service file
sudo cp picoclaw-mcp.service /etc/systemd/system/

# Reload systemd
sudo systemctl daemon-reload

# Enable and start the service
sudo systemctl enable picoclaw-mcp
sudo systemctl start picoclaw-mcp

# Check status
sudo systemctl status picoclaw-mcp

Systemd Service Customization

Edit the service file to customize:

[Service]
Environment="OPENCODE_REPO_URL=https://github.com/yourusername/your-repo"
Environment="OPENCODE_REFRESH_INTERVAL=1800"
Environment="HEADLESS=true"

Development

# Run with MCP Inspector
uv run mcp dev server.py

# Run directly
python server.py

License

MIT