This is an MCP service implementation built upon [Scrapybara](https://scrapybara.com). It exposes functionality allowing MCP-aware applications, such as [Claude Desktop](https://claude.ai/download), [Cursor](https://www.cursor.com/), and [Windsurf](https://codeium.com/windsurf), to programmatically interact with sandboxed Ubuntu virtual machines, facilitating tasks like browsing the internet or executing system commands. ## Setup Requirements * Node.js runtime, version 18 or higher is mandatory. * The pnpm package manager. * A valid Scrapybara access key, obtainable from [scrapybara.com](https://scrapybara.com) ## Deployment Steps 1. Clone the source repository: bash git clone https://github.com/scrapybara/scrapybara-mcp.git cd scrapybara-mcp 2. Install project dependencies: bash pnpm install 3. Compile the project assets: bash pnpm build 4. Integrate the following configuration snippet into your MCP client's settings file: { "mcpServers": { "virtual-desktop-orchestrator-mcp": { "command": "node", "args": ["path/to/scrapybara-mcp/dist/index.js"], "env": { "SCRAPYBARA_API_KEY": "", "ACT_MODEL": "", // Specify interaction model: "anthropic" or "openai" "AUTH_STATE_ID": "" // Optional credential for browser session linkage } } } } 5. Reload or restart your MCP consuming application to activate the new server. ## Available Operations - **start_instance** - Initializes a new Scrapybara Ubuntu environment. This serves as an isolated sandbox for web interaction or command execution. The operation mandates returning the streaming URL for user observation. - **get_instances** - Retrieves a roster of all presently active Scrapybara virtual machines. - **stop_instance** - Terminates a specified, currently running Scrapybara session. - **bash** - Executes arbitrary shell commands within the target Scrapybara machine's environment. - **act** - Enables agent-driven interaction with the session. The agent can simulate user input (mouse/keyboard) and execute system commands to manipulate the desktop state. ## Community Involvement Scrapybara MCP thrives on community input. Submissions of feature suggestions, error corrections, tool additions, or improvements to existing features are highly valued. Please review existing tickets before proposing new work to prevent redundant efforts. Suggestions for novel capabilities or missing tools should be posted on the [issues tracker](https://github.com/scrapybara/scrapybara-mcp/issues). WIKIPEDIA: A headless browser is a web browser without a graphical user interface. Headless browsers provide automated control of a web page in an environment similar to popular web browsers, but they are executed via a command-line interface or using network communication. They are particularly useful for testing web pages as they are able to render and understand HTML the same way a browser would, including styling elements such as page layout, color, font selection and execution of JavaScript and Ajax which are usually not available when using other testing methods. Since version 59 of Google Chrome and version 56 of Firefox, there is native support for remote control of the browser. This made earlier efforts obsolete, notably PhantomJS. == Use cases == The main use cases for headless browsers are: Test automation in modern web applications (web testing) Taking screenshots of web pages. Running automated tests for JavaScript libraries. Automating interaction of web pages. === Other uses === Headless browsers are also useful for web scraping. Google stated in 2009 that using a headless browser could help their search engine index content from websites that use Ajax. Headless browsers have also been misused in various ways: Perform DDoS attacks on web sites. Increase advertisement impressions. Automate web sites in unintended ways e.g. for credential stuffing. However, a study of browser traffic in 2018 found no preference by malicious actors for headless browsers. There is no indication that headless browsers are used more frequently than non-headless browsers for malicious purposes, like DDoS attacks, SQL injections or cross-site scripting attacks. == Usage == As several major browsers natively support headless mode through APIs, some software exists to perform browser automation through a unified interface. These include: Selenium WebDriver – a W3C compliant implementation of WebDriver Playwright – a Node.js library to automate Chromium, Firefox and WebKit Puppeteer – a Node.js library to automate Chrome or Firefox === Test automation === Some test automation software and frameworks include headless browsers as part of their testing apparati. Capybara uses headless browsing, either via WebKit or Headless Chrome to mimic user behavior in its testing protocols. Jasmine uses Selenium by default, but can use WebKit or Headless Chrome, to run browser tests. Cypress, a frontend testing framework QF-Test, a software tool for automated testing of programs via the graphical user interface where a headless browser can also be used for testing. === Alternatives === Another approach is to use software that provides browser APIs. For example, Deno provides browser APIs as part of its design. For Node.js, jsdom is the most complete provider. While most are able to support common browser features (HTML parsing, cookies, XHR, some JavaScript, etc.), they do not render the DOM and have limited support for DOM events. They usually perform faster than