Rf Mcp

🤖 RobotMCP - AI-Powered Test Automation Bridge

[](https://python.org) [](https://robotframework.org) [](https://github.com/jlowin/fastmcp) [](LICENSE)

Transform natural language into production-ready Robot Framework tests using AI agents and MCP protocol.

RobotMCP is a comprehensive Model Context Protocol (MCP) server that bridges the gap between human language and Robot Framework automation. It enables AI agents to understand test intentions, execute steps interactively, and generate complete test suites from successful executions.

📺 Video Tutorial

[](https://www.youtube.com/watch?v=CBXGEn8jRtU)

Intro

https://github.com/user-attachments/assets/ad89064f-cab3-4ae6-a4c4-5e8c241301a1

---

✨ Quick Start

1️⃣ Install

pip install rf-mcp

2️⃣ Add to VS Code (Cline/Claude Desktop)

STDIO

{
  "servers": {
    "robotmcp": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "-m", "robotmcp.server"]
    }
  }
}

HTTP

Start the MCP server with HTTP transport:

uv run -m robotmcp.server --transport http --host 127.0.0.1 --port 8000

Then configure your AI agent:

{
  "servers": {
    "robotmcp": {
      "type": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

Claude Code

claude mcp add rf-mcp -- uvx rf-mcp

3️⃣ Start Testing with AI

Use #robotmcp to create a TestSuite and execute it step wise.
Create a test for https://www.saucedemo.com/ that:
- Logs in to https://www.saucedemo.com/ with valid credentials
- Adds two items to cart
- Completes checkout process
- Verifies success message

Use Selenium Library.
Execute the test suite stepwise and build the final version afterwards.

That's it! RobotMCP will guide the AI through the entire testing workflow.

---

🛠️ Installation & Setup

https://github.com/user-attachments/assets/8448cb70-6fb3-4f04-9742-a8a8453a9c7f

Prerequisites

• Python 3.10+
• Robot Framework 7.0+
• FastMCP 2.8+ (compatible with both 2.x and 3.x)

rf-mcp comes with minimal dependencies by default. To use specific libraries (e.g., Browser, Selenium, Appium), install the corresponding extras or libraries separately.

Method 1: UV Installation (Recommended)

# Install with uv pip wrapper
uv venv   # create a virtual environment
uv pip install rf-mcp

# Feature bundles (install what you need)
uv pip install rf-mcp[web]       # Browser Library + SeleniumLibrary
uv pip install rf-mcp[mobile]    # AppiumLibrary
uv pip install rf-mcp[api]       # RequestsLibrary
uv pip install rf-mcp[database]  # DatabaseLibrary
uv pip install rf-mcp[frontend]  # Django-based web frontend dashboard
uv pip install rf-mcp[memory]    # Persistent semantic memory (sqlite-vec + model2vec)
uv pip install rf-mcp[semantic]  # Sentence-transformers for find_keywords embedding ranking
uv pip install rf-mcp[all]       # All optional Robot Framework libraries

# Alternatively, add to an existing uv project
uv init
# Add rf-mcp to project dependencies and sync
uv add rf-mcp[all]
uv sync

# Browser Library still needs Playwright browsers
uv run rfbrowser init

Method 2 PyPI Installation

# Install RobotMCP core (minimal dependencies)
pip install rf-mcp

# Feature bundles (install what you need)
pip install rf-mcp[web]       # Browser Library + SeleniumLibrary
pip install rf-mcp[mobile]    # AppiumLibrary
pip install rf-mcp[api]       # RequestsLibrary
pip install rf-mcp[database]  # DatabaseLibrary
pip install rf-mcp[frontend]  # Django-based web frontend dashboard
pip install rf-mcp[memory]    # Persistent semantic memory (sqlite-vec + model2vec)
pip install rf-mcp[semantic]  # Sentence-transformers for find_keywords embedding ranking
pip install rf-mcp[all]       # All optional Robot Framework libraries

# Browser Library still needs Playwright browsers
rfbrowser init
# or
python -m Browser.entry install

Prefer installing individual Robot Framework libraries instead? Just install rf-mcp and add your desired libraries manually.

Method 3: Development Installation

# Clone repository
git clone https://github.com/manykarim/rf-mcp.git
cd rf-mcp

# Install with uv (recommended)
uv sync
# Include optional extras & dev tooling
uv sync --all-extras --dev

# Or with pip
pip install -e .

Method 4: Docker Installation

RobotMCP provides pre-built Docker images for both headless and VNC-enabled environments.

Headless Image (Recommended for CI/CD)

# Pull from GitHub Container Registry
docker pull ghcr.io/manykarim/rf-mcp:latest

# Run with HTTP transport and frontend
docker run -p 8000:8000 -p 8001:8001 ghcr.io/manykarim/rf-mcp:latest

# Or run interactively with STDIO
docker run -it --rm ghcr.io/manykarim/rf-mcp:latest uv run robotmcp

Included browsers: Chromium, Firefox ESR, Playwright browsers (Chromium, Firefox, WebKit)

VNC Image (For Visual Debugging)

The VNC image includes a full X11 desktop accessible via VNC or noVNC web interface:

# Pull VNC image
docker pull ghcr.io/manykarim/rf-mcp-vnc:latest

# Run with all ports exposed
docker run -p 8000:8000 -p 8001:8001 -p 5900:5900 -p 6080:6080 ghcr.io/manykarim/rf-mcp-vnc:latest

Access points: | Port | Service | |------|---------| | 8000 | MCP HTTP transport | | 8001 | Frontend dashboard | | 5900 | VNC (use any VNC client) | | 6080 | noVNC web interface (http://localhost:6080/vnc.html) |

Building Docker Images Locally

# Build headless image
docker build -f docker/Dockerfile -t robotmcp .

# Build VNC image
docker build -f docker/Dockerfile.vnc -t robotmcp-vnc .

Using Docker with VS Code MCP

STDIO mode:

{
  "servers": {
    "robotmcp": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/manykarim/rf-mcp:latest", "uv", "run", "robotmcp"]
    }
  }
}

HTTP mode (start container first, then connect):

{
  "servers": {
    "robotmcp": {
      "type": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

Playwright/Browsers for UI Tests

• Browser Library: run rfbrowser init (downloads Playwright and browsers)

Hint: When using a venv

If you are using a virtual environment (venv) for your project, I recommend to install the rf-mcp package within the same venv. When starting the MCP server, make sure to use the Python interpreter from that venv.

---

🔌 Library Plugins

Extend RobotMCP with custom libraries via the plugin system. Two discovery modes are available:

• Entry points (robotmcp.library_plugins) for packaged plugins.
• Manifest files (JSON) under .robotmcp/plugins/ for workspace overrides.

See the [Library Plugin Authoring Guide](docs/library-plugin-authoring.md) for detailed instructions and explore the sample plugin in [examples/plugins/sample_plugin](examples/plugins/sample_plugin/) to get started quickly.

---

🖥️ Frontend Dashboard

RobotMCP ships with an optional Django-based dashboard that mirrors active sessions, keywords, and tool activity.

1. Install frontend extras

``bash pip install rf-mcp[frontend] ``

1. Start the MCP server with the frontend enabled

``bash uv run -m robotmcp.server --with-frontend ``

• Default URL:
• Quick toggles: --frontend-host, --frontend-port, --frontend-base-path
• Environment equivalents: ROBOTMCP_ENABLE_FRONTEND=1, ROBOTMCP_FRONTEND_HOST, ROBOTMCP_FRONTEND_PORT, ROBOTMCP_FRONTEND_BASE_PATH, ROBOTMCP_FRONTEND_DEBUG

1. Connect your MCP client (Cline, Claude Desktop, etc.) to the same server process—the dashboard automatically streams events once the session is active.

To disable the dashboard for a given run, either omit the flag or pass --without-frontend.

---

📋 Instruction Templates

RobotMCP sends server-level instructions to LLMs via the MCP initialize response, guiding them to discover keywords before executing them. This significantly reduces failed tool calls and wasted tokens, especially for smaller LLMs.

Configuration

Three environment variables control instruction behavior:

| Variable | Values | Default | |----------|--------|---------| | ROBOTMCP_INSTRUCTIONS | off / default / custom | default | | ROBOTMCP_INSTRUCTIONS_TEMPLATE | minimal / standard / detailed / browser-focused / api-focused | standard | | ROBOTMCP_INSTRUCTIONS_FILE | Path to .txt or .md file | (none, required when mode=custom) |

Built-in Templates

| Template | ~Tokens | Best For | |----------|---------|----------| | minimal | ~40 | Capable LLMs (Claude Opus, GPT-4) — brief reminder only | | standard | ~400 | Mid-range LLMs (Claude Sonnet, GPT-4o) — balanced workflow guide | | detailed | ~600 | Smaller LLMs (Claude Haiku, GPT-4o-mini) — step-by-step with examples | | browser-focused | ~350 | Web-only testing scenarios | | api-focused | ~300 | API-only testing scenarios |

Example

{
  "servers": {
    "robotmcp": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "-m", "robotmcp.server"],
      "env": {
        "ROBOTMCP_INSTRUCTIONS": "default",
        "ROBOTMCP_INSTRUCTIONS_TEMPLATE": "detailed"
      }
    }
  }
}

Custom Instructions

Set ROBOTMCP_INSTRUCTIONS=custom and provide a file via ROBOTMCP_INSTRUCTIONS_FILE. Custom files support {available_tools} placeholder substitution. Allowed extensions: .txt, .md, .instruction, .instructions. If the file is missing or fails validation, the server falls back to the standard template automatically.

See [docs/INSTRUCTIONTEMPLATESGUIDE.md](docs/INSTRUCTIONTEMPLATESGUIDE.md) for the full guide.

---

🪝 Debug Attach Bridge

https://github.com/user-attachments/assets/8d87cd6e-c32e-4481-9f37-48b83f69f72f

RobotMCP ships with robotmcp.attach.McpAttach, a lightweight Robot Framework library that exposes the live ExecutionContext over a localhost HTTP bridge. When you debug a suite from VS Code (RobotCode) or another IDE, the bridge lets RobotMCP reuse the in-process variables, imports, and keyword search order instead of creating a separate context.

MCP Server Setup

Example configuration with passed environment variables for Debug Bridge

Using UV

{
  "servers": {
    "RobotMCP": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "src/robotmcp/server.py"],
      "env": {
        "ROBOTMCP_ATTACH_HOST": "127.0.0.1",
        "ROBOTMCP_ATTACH_PORT": "7317",
        "ROBOTMCP_ATTACH_TOKEN": "change-me",
        "ROBOTMCP_ATTACH_DEFAULT": "auto"
      }
    }
  }
}

Using Docker

{
  "servers": {
    "RobotMCP": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/manykarim/rf-mcp:latest", "uv", "run", "robotmcp"],
      "env": {
        "ROBOTMCP_ATTACH_HOST": "127.0.0.1",
        "ROBOTMCP_ATTACH_PORT": "7317",
        "ROBOTMCP_ATTACH_TOKEN": "change-me",
        "ROBOTMCP_ATTACH_DEFAULT": "auto"
      }
    }
  }
}

Robot Framework setup

Import the library and start the serve loop inside the suite that you are debugging:

*** Settings ***
Library    robotmcp.attach.McpAttach    token=${DEBUG_TOKEN}

*** Variables ***
${DEBUG_TOKEN}    change-me

*** Test Cases ***
Serve From Debugger
    MCP Serve    port=7317    token=${DEBUG_TOKEN}    mode=blocking    poll_ms=100
    [Teardown]    MCP Stop

• MCP Serve port=7317 token=${TOKEN} mode=blocking|step poll_ms=100 — starts the HTTP server (if not running) and processes bridge commands. Use mode=step during keyword body execution to process exactly one queued request.
• MCP Stop — signals the serve loop to exit (used from the suite or remotely via RobotMCP attach_stop_bridge).
• MCP Process Once — processes a single pending request and returns immediately; useful when the suite polls between test actions.
• MCP Start — alias for MCP Serve for backwards compatibility.

The bridge binds to 127.0.0.1 by default and expects clients to send the shared token in the X-MCP-Token header.

Configure RobotMCP to attach

Start robotmcp.server with attach routing by providing the bridge connection details via environment variables (token must match the suite):

export ROBOTMCP_ATTACH_HOST=127.0.0.1
export ROBOTMCP_ATTACH_PORT=7317          # optional, defaults to 7317
export ROBOTMCP_ATTACH_TOKEN=change-me    # optional, defaults to 'change-me'
export ROBOTMCP_ATTACH_DEFAULT=auto       # auto|force|off (auto routes when reachable)
export ROBOTMCP_ATTACH_STRICT=0           # set to 1/true to fail when bridge is unreachable
uv run python -m robotmcp.server

When ROBOTMCP_ATTACH_HOST is set, execute_step(..., use_context=true) and other context-aware tools first try to run inside the live debug session. Use the new MCP tools to manage the bridge from any agent:

• attach_status — reports configuration, reachability, and diagnostics from the bridge (/diagnostics).
• attach_stop_bridge — sends a /stop command, which in turn triggers MCP Stop in the debugged suite.

---

🎪 Example Workflows

🌐 Web Application Testing (BDD)

Prompt:

Use RobotMCP to create a test suite and execute it step wise.
It shall:

- Open https://demoshop.makrocode.de/
- Add item to cart
- Assert item was added to cart
- Add another item to cart
- Assert another item was added to cart
- Checkout
- Assert checkout was successful

Execute step by step and build final test suite afterwards
Create in BDD style and use Keywords with embedded arguments when applicable

Result: BDD-style Robot Framework test suite with Given/When/Then keywords, embedded arguments, and extracted variables.

🌐 Web Application Testing (Data-Driven)

Prompt:

Use RobotMCP to create a test suite and execute it step wise.
It shall:

- Open https://saucedemo.com
- Login with different user/password combinations
- Assert message or login

Execute step by step and build final test suite afterwards
Create in datadriven style and add multiple test rows with different scenarios
Use Test Template setting in suite

Result: Data-driven Robot Framework test suite with Test Template and parameterized rows for each login scenario.

📱 Mobile App Testing

Prompt:

Use RobotMCP to create a TestSuite and execute it step wise.
It shall:
- Launch app from tests/appium/SauceLabs.apk
- Perform login flow
- Add products to cart
- Complete purchase

Appium server is running at http://localhost:4723
Execute the test suite stepwise and build the final version afterwards.

Result: Mobile test suite with AppiumLibrary keywords and device capabilities.

🔌 API Testing

Prompt:

Read the Restful Booker API documentation at https://restful-booker.herokuapp.com.
Use RobotMCP to create a TestSuite and execute it step wise.
It shall:

- Create a new booking
- Authenticate as admin
- Update the booking
- Delete the booking
- Verify each response

Execute the test suite stepwise and build the final version afterwards.

Result: API test suite using RequestsLibrary with proper error handling.

🧪 XML/Database Testing

Prompt:

Create a xml file with books and authors.
Use RobotMCP to create a TestSuite and execute it step wise.
It shall:
- Parse XML structure
- Validate specific nodes and attributes
- Assert content values
- Check XML schema compliance

Execute the test suite stepwise and build the final version afterwards.

Result: XML processing test using Robot Framework's XML library.

---

🔍 MCP Tools Overview

RobotMCP provides a comprehensive toolset organized by function. Highlights:

Planning & Orchestration

• analyze_scenario – Convert natural language to structured test intent and spawn sessions.
• recommend_libraries – Suggest libraries (mode="direct", "sampling_prompt", or "merge_samples"). Includes confide

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: manykarim
• Source: manykarim/rf-mcp
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.