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.
Intro
RobotMCP_anouncement.mp4
Setup
rf-mcp_setup.mp4
Debug Bridge
rf-mcp_debug.mp4
pip install rf-mcp{
"servers": {
"robotmcp": {
"type": "stdio",
"command": "python",
"args": ["-m", "robotmcp.server"]
}
}
}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.
- Convert human test descriptions into structured actions
- Intelligent scenario analysis and library recommendations
- Context-aware test planning (web, mobile, API, database)
- Execute Robot Framework keywords step-by-step
- Real-time state tracking and session management
- Native RF context runner for correct argument parsing and types
- Smart error handling with actionable suggestions
- Advanced locator guidance for Browser Library & SeleniumLibrary
- Cross-library locator conversion (Browser β Selenium)
- DOM filtering and element discovery
- Generate optimized Robot Framework test suites
- Maintain proper imports, setup/teardown, and documentation
- Support for tags, variables, and test organization
- Includes session Resources/Libraries in *** Settings ***
- Portable path formatting using ${/} (Windows-safe)
- Web: Browser Library (Playwright) & SeleniumLibrary
- Mobile: AppiumLibrary for iOS/Android testing
- API: RequestsLibrary for HTTP/REST testing
- Database: DatabaseLibrary for SQL operations
- MCP Debug Attach Bridge: drive RobotMCP tools against a live Robot Framework debug session via the new
McpAttachlibrary and attach-aware tools. - RF native context execution: persistent per-session Namespace + ExecutionContext.
- Runner-first keyword execution with BuiltIn fallback for maximum compatibility.
- New tools to import Resources and custom Python libraries into the session context.
- Session-aware keyword discovery and documentation.
- Test suite generation now reflects session imports and uses OS-independent paths.
- CI pipeline via uv across Windows/macOS/Linux; Browser/Playwright initialization included.
Details below.
- Python 3.10+
- Robot Framework 6.0+
# Install RobotMCP core (minimal dependencies)
pip install rf-mcp
# or explicitly
pip install rf-mcp[slim]
# 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[all] # All optional Robot Framework libraries
# Browser Library still needs Playwright browsers
rfbrowser init
# or
python -m Browser.entry installPrefer installing individual Robot Framework libraries instead? You still canβ each extra maps 1:1 to the original packages and their setup guidance below.
# 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 .- Browser Library: run
rfbrowser init(downloads Playwright and browsers)
If you are using a virtual environment (venv) for your project, I recommend to install the rf-mcp package within the same venv.
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 for detailed instructions and explore the sample plugin in examples/plugins/sample_plugin to get started quickly.
When starting the MCP server, make sure to use the Python interpreter from that venv.
RobotMCP ships with an optional Django-based dashboard that mirrors active sessions, keywords, and tool activity.
- Install frontend extras
pip install rf-mcp[frontend]
- Start the MCP server with the frontend enabled
uv run python -m robotmcp.server --with-frontend
- Default URL: http://127.0.0.1:8001/
- 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
- 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.
{
"servers": {
"robotmcp": {
"type": "stdio",
"command": "uv",
"args": ["run", "python", "-m", "robotmcp.server"]
}
}
}{
"servers": {
"robotmcp": {
"type": "stdio",
"command": "python",
"args": ["-m", "robotmcp.server"]
}
}
}Hint: If you set up a virtual environment, make sure to also use the python executable from that venv to start the server.
Location: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
{
"mcpServers": {
"robotmcp": {
"command": "python",
"args": ["-m", "robotmcp.server"]
}
}
}RobotMCP works with any MCP-compatible AI agent. Use the stdio configuration above.
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.
Example configuration with passed environment variables for Debug Bridge
{
"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"
}
}
}
}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 StopMCP Serve port=7317 token=${TOKEN} mode=blocking|step poll_ms=100β starts the HTTP server (if not running) and processes bridge commands. Usemode=stepduring keyword body execution to process exactly one queued request.MCP Stopβ signals the serve loop to exit (used from the suite or remotely via RobotMCPattach_stop_bridge).MCP Process Onceβ processes a single pending request and returns immediately; useful when the suite polls between test actions.MCP Startβ alias forMCP Servefor 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.
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.serverWhen 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/stopcommand, which in turn triggersMCP Stopin the debugged suite.
Prompt:
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.
Result: Complete Robot Framework test suite with proper locators, assertions, and structure.
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.
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.
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.
RobotMCP provides a comprehensive toolset organized by function. Highlights:
analyze_scenarioβ Convert natural language to structured test intent and spawn sessions.recommend_librariesβ Suggest libraries (mode="direct","sampling_prompt", or"merge_samples").manage_library_pluginsβ List, reload, or diagnose library plugins from a single endpoint.
manage_sessionβ Initialize sessions, import resources/libraries, or set variables viaaction.execute_stepβ Execute keywords ormode="evaluate"expressions with optionalassign_to.execute_flowβ Buildif/for_each/trycontrol structures using RF context-first execution.
find_keywordsβ Unified keyword discovery (semantic, pattern, catalog, or session scopes).get_keyword_infoβ Retrieve keyword/library documentation or parse argument signatures (mode="keyword"|"library"|"session"|"parse").
get_session_stateβ Aggregate session insight (summary,variables,page_source,application_state,validation,libraries,rf_context).check_library_availabilityβ Verify availability/install guidance for specific libraries (always includessuccess).set_library_search_orderβ Control keyword resolution precedence.manage_attachβ Inspect or stop the attach bridge.
build_test_suiteβ Generate Robot Framework test files from validated steps.run_test_suiteβ Validate (mode="dry") or execute (mode="full") suites.
get_locator_guidanceβ Consolidated Browser/Selenium/Appium selector guidance with structured output.
For detailed tool documentation, see the Tools Reference section.
π¦ ExecutionCoordinator (Main Orchestrator)
βββ π€ SessionManager - Session lifecycle & library management
βββ βοΈ KeywordExecutor - RF keyword execution engine
βββ π BrowserLibraryManager - Browser/Selenium library switching
βββ π PageSourceService - DOM extraction & filtering
βββ π LocatorConverter - Cross-library locator translation
βββ π SuiteExecutionService - Test suite generation & execution
- ArgumentResolver - Native RF argument parsing
- TypeConverter - RF type conversion (string β int/bool/etc.)
- LibDoc API - Direct RF documentation access
- Keyword Discovery - Runtime detection using RF internals
- Runner First - Execute via Namespace.get_runner(...).run(...), fallback to BuiltIn.run_keyword
- Auto-configuration based on scenario analysis
- Browser library conflict resolution (Browser vs Selenium)
- Cross-session state persistence
- Mobile capability detection and setup
Convert natural language test descriptions into structured test intents with automatic session creation.
{
"scenario": "Test user login with valid credentials",
"context": "web",
"session_id": "optional-session-id"
}Execute individual Robot Framework keywords with advanced session management.
{
"keyword": "Fill Text",
"arguments": ["css=input[name='username']", "testuser"],
"session_id": "default",
"detail_level": "minimal"
}Generate production-ready Robot Framework test suites from executed steps.
{
"test_name": "User Login Test",
"session_id": "default",
"tags": ["smoke", "login"],
"documentation": "Test successful user login flow"
}Get comprehensive Browser Library locator strategies and error guidance.
{
"error_message": "Strict mode violation: multiple elements found",
"keyword_name": "Click"
}Returns:
- 10 Playwright locator strategies (css=, xpath=, text=, id=, etc.)
- Advanced features (cascaded selectors, iframe piercing, shadow DOM)
- Error-specific guidance and suggestions
- Best practices for element location
Inspect the attach bridge configuration and diagnostics before routing execute_step calls into a live debug session.
{}Returns:
configured: whether attach mode is active (based onROBOTMCP_ATTACH_HOST)host,port: bridge connection values when configuredreachable: true when/diagnosticssucceeds; includes diagnostics payload when availabledefault_mode: value ofROBOTMCP_ATTACH_DEFAULT(auto|force|off)strict: true whenROBOTMCP_ATTACH_STRICTdemands a reachable bridgehint: actionable guidance when not configured or unreachable
Send a stop command to the McpAttach bridge to exit MCP Serve inside the debugged suite.
{}Returns:
success: true when the bridge acknowledged the stop requestresponse: raw payload returned by the bridge ({"success": true}on success)
Get comprehensive SeleniumLibrary locator strategies and troubleshooting.
{
"error_message": "Element not found: name=firstname",
"keyword_name": "Input Text"
}Returns:
- 14 SeleniumLibrary locator strategies (id:, name:, css:, xpath:, etc.)
- Locator format analysis and recommendations
- Timeout and waiting strategy guidance
- Element location best practices
For complete tool documentation, see the source code docstrings.
*** Settings ***
Documentation Test suite for validating the complete checkout process on Sauce Demo website
Library Browser
Library Collections
Force Tags e2e checkout smoke
*** Variables ***
${URL} https://www.saucedemo.com/
${USERNAME} standard_user
${PASSWORD} secret_sauce
${FIRST_NAME} John
${LAST_NAME} Doe
${POSTAL_CODE} 12345
${EXPECTED_SUCCESS_MSG} Thank you for your order!
*** Test Cases ***
Complete Checkout Process Test
[Documentation] Validates the complete checkout process on Sauce Demo:
... 1. Opens the website
... 2. Logs in with valid credentials
... 3. Adds items to cart
... 4. Completes checkout process
# Setup and login
Open Browser And Navigate To Login Page
Login With Valid Credentials
Verify Successful Login
# Add items to cart
Add Item To Cart id=add-to-cart-sauce-labs-backpack
Verify Item Count In Cart 1
Add Item To Cart id=add-to-cart-sauce-labs-bike-light
Verify Item Count In Cart 2
# Checkout process
Go To Cart
Start Checkout
Fill Checkout Information
Complete Checkout
# Verify successful checkout
Verify Checkout Success
# Cleanup
Close Browser
*** Keywords ***
Open Browser And Navigate To Login Page
New Browser chromium headless=False
New Context viewport={'width': 1280, 'height': 720}
New Page ${URL}
Login With Valid Credentials
Fill Text id=user-name ${USERNAME}
Fill Text id=password ${PASSWORD}
Click id=login-button
Verify Successful Login
Wait For Elements State .inventory_list visible
${current_url}= Get Url
Should Contain ${current_url} inventory.html
Add Item To Cart
[Arguments] ${item_id}
Click ${item_id}
Verify Item Count In Cart
[Arguments] ${expected_count}
${cart_count}= Get Text .shopping_cart_badge
Should Be Equal As Strings ${cart_count} ${expected_count}
Go To Cart
Click .shopping_cart_link
Start Checkout
Click id=checkout
Fill Checkout Information
Fill Text id=first-name ${FIRST_NAME}
Fill Text id=last-name ${LAST_NAME}
Fill Text id=postal-code ${POSTAL_CODE}
Click id=continue
Complete Checkout
Click id=finish
Verify Checkout Success
${success_message}= Get Text h2
Should Be Equal As Strings ${success_message} ${EXPECTED_SUCCESS_MSG}Original prompt:
Use RobotMCP to create a TestSuite and execute it step wise.
- Open https://www.saucedemo.com/
- Login with valid user
- Assert login was successful
- 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.
Make a clean and maintainable test suiteUse analyze_scenario to understand test requirements and create session
Get recommendations with recommend_libraries
Check availability with check_library_availability
Execute steps one by one with execute_step
Get page state with get_page_source
Use locator guidance tools for element issues
Validate session with get_session_validation_status
Generate suite with build_test_suite
Validate syntax with run_test_suite_dry
Execute with run_test_suite
- Use
get_page_sourcewithfiltered=trueto see automation-relevant elements - Leverage locator guidance tools when elements aren't found
- Browser Library supports modern selectors (text=, data-testid=, etc.)
- Use
detail_level="minimal"to reduce response size by 80-90% - Enable DOM filtering to focus on interactive elements
- Session management maintains state across interactions
- Execute steps individually before building suites
- Use
run_test_suite_dryto catch issues early - Leverage native RF integration for maximum compatibility
- Prefer context mode for BuiltIn keywords (Evaluate, Set Variables, control flow)
execute_stepauto-retries via RF context when a keyword isnβt found
- Sessions auto-detect context (web/mobile/api) from scenarios
- Library conflicts are automatically resolved
- Mobile sessions configure Appium capabilities automatically
- Test suite paths use
${/}for OS-independent imports; module names stay as-is
We welcome contributions! Here's how to get started:
- Fork the repository
- Clone your fork locally
- Install development dependencies:
uv sync - Create a feature branch
- Add comprehensive tests for new functionality
- Run tests:
uv run pytest tests/ - Submit a pull request
# Run Browser/Selenium focused tests
uv run pytest -m optional_web -q
# Run API smoke tests
uv run pytest -m optional_api -q
# Run combined web+api tests
uv run pytest -m optional_web_api -q
# Convenience helper (installs extras + executes markers)
python scripts/run_optional_tests.py web api web+api# Run tests
uv run pytest tests/
# Format code
uv run black src/
# Type checking
uv run mypy src/
# Start development server
uv run python -m robotmcp.server
# Build package
uv build- Persistent per-session Namespace + ExecutionContext are created on demand.
- Runner-first dispatch:
Namespace.get_runner(...).run(...), with fallback toBuiltIn.run_keyword. - Variables and imports persist within the session;
get_context_variablessurfaces a sanitized snapshot. - RequestsLibrary session keywords default to runner path; disable via
ROBOTMCP_RF_RUNNER_REQUESTS=0. - Non-context executions automatically retry in RF context when a keyword cannot be resolved (helps user keywords/resources).
Common cases that require use_context=true in execute_step:
- BuiltIn control flow and variables: Evaluate, Set Test/Suite/Global Variable, Run Keywords
- Keywords relying on session imports/resources
- Complex named/positional/mixed arguments where RFβs resolver is desired
- Matrix for Python 3.10β3.12 on Ubuntu, macOS, Windows
- Uses
astral-sh/setup-uvanduv syncfor installs - Initializes Browser Library with
rfbrowser init(continues on error) - Runs tests via
uv run pytest - Builds artifacts with
uv buildand uploadsdist/*
Apache 2.0 License - see LICENSE file for details.
- π€ Agent-Optimized: Structured responses designed for AI processing
- π§ Context-Aware: Rich error messages with actionable guidance
- β‘ Token-Efficient: Minimal response mode reduces costs significantly
- π‘οΈ Production-Ready: Native Robot Framework integration
- π§ Flexible: Multi-library support (Browser, Selenium, Appium, etc.)
- π Comprehensive: 20 tools covering complete automation workflow
- π Maintainable: Generates clean, documented Robot Framework code
- π Iterative: Step-by-step development and validation
- π Scalable: Session-based architecture supports complex scenarios
- π Issues: GitHub Issues
- π‘ Feature Requests: GitHub Discussions
- π Documentation: Tool docstrings and examples
- π Latest Updates: Check releases for new features
β Star us on GitHub if RobotMCP helps your test automation journey!
Made with β€οΈ for the Robot Framework and AI automation community.
