ByteBot

You run a production-grade MCP server that unifies ByteBot’s Task Management and Desktop Control APIs. This server enables autonomous task execution, direct computer control, and hybrid workflows with optional live updates, making complex automation and desktop orchestration practical and reliable.

How to use

You interact with the ByteBot MCP Server through an MCP client to create, monitor, and execute tasks that control both autonomous workflows and desktop actions. Use the Task Management tools to create and manage tasks, and use the Desktop Control tools to move the mouse, type text, capture screens, read or write files, and switch applications. For long-running or multi-step processes, you can employ hybrid orchestration to create a task and monitor it until completion, with automatic intervention when needed.

How to install

Prerequisites: ensure you have Node.js 20.x or higher installed on your system.

1. Prepare the project locally by obtaining the MCP server code. Then open a terminal and navigate to the project directory.

2. Install dependencies.

npm install

3. Build the TypeScript code.

npm run build

4. Create and customize your environment file from the example.

cp .env.example .env

5. Start the MCP server (the exact start command is provided by your run script or package.json in most setups). If you are following the project’s standard flow, you will run the built server script from the distribution path.

Configuration and runtime notes

Configure the client connections and runtime options through an environment file. The keys you typically set include the URLs to the ByteBot Agent API and Desktop API, optional WebSocket settings, server identity, timeouts, retry behavior, polling intervals, and file size limits.

Example environment variables you’ll adjust include ByteBot endpoints, WebSocket settings, and various timeouts. These settings let you tune responsiveness, reliability, and resource usage for your deployment.

Troubleshooting

If you encounter connection or timeout issues, verify that ByteBot services are reachable at the configured endpoints and that the MCP server is running with the expected environment variables. Check for firewall rules blocking HTTP or WebSocket connections and ensure the agent and desktop services are accessible.

If a task stalls, review the task’s status and messages via the MCP client, and consider increasing request and action timeouts in your environment configuration. For long-running tasks, you can use the hybrid workflow tools to monitor progress and handle interventions automatically.

If a screenshot or file operation reports size or permission issues, adjust the corresponding MAX_FILE_SIZE value and ensure file paths are correct and accessible by the MCP server process.

Environment variables reference

Key environment variables control how the MCP server connects to ByteBot and how it operates. You will typically set these in your .env file before starting the server.

Tools and capabilities overview

The MCP server exposes a set of prototype tools organized into Agent API tools for task management, Desktop API tools for desktop control, and Hybrid Orchestration tools for coordinated workflows. These tools enable you to create tasks, monitor progress, perform desktop actions, and run multi-step workflows with automatic recovery.

Available tools

bytebot_create_task

Create new tasks with priority levels for ByteBot to execute.

bytebot_list_tasks

List and filter tasks by status or priority.

bytebot_get_task

Get detailed information about a specific task, including message history.

bytebot_get_in_progress_task

Check the currently running task.

bytebot_update_task

Update a task's status or priority.

bytebot_delete_task

Delete tasks.

bytebot_move_mouse

Move the mouse cursor to specified coordinates.

bytebot_click

Click mouse buttons (left, right, middle) with optional coordinates.

bytebot_drag

Drag the cursor from one position to another.

bytebot_scroll

Scroll in a direction with a given amount.

bytebot_type_text

Type text strings into focused input fields.

bytebot_paste_text

Paste text, including special characters.

bytebot_press_keys

Press keyboard shortcuts like Ctrl+C or Alt+Tab.

bytebot_screenshot

Capture the screen as a base64-encoded PNG.

bytebot_cursor_position

Get the current cursor position.

bytebot_read_file

Read file contents and return as base64.

bytebot_write_file

Write base64 content to a file.

bytebot_switch_application

Switch focus to a specified application.

bytebot_wait

Wait for a specified duration before proceeding.

bytebot_create_and_monitor_task

Create a task and monitor it until completion with automatic handling.

bytebot_monitor_task

Monitor an existing task until it reaches a terminal state.

bytebot_intervene_in_task

Provide user intervention for a task that needs input.

bytebot_execute_workflow

Run a multi-step workflow with automatic error recovery.