Skip to main content
Glama

rf-mcp — Robot Framework Agentic Engineering MCP Server

IMPORTANT

rf-mcp is being heavily refactored. Version 2.0 rebuilds it on the RobotCode CLI, and this README already describes that new implementation. See the 2.0 release notes for what changed.

2.0 is not on PyPI yet, so pip install rf-mcp and uv add rf-mcp still install 0.36.x. To try 2.0 now, install it from GitHub:

uv add --dev "rf-mcp @ git+https://github.com/manykarim/rf-mcp" "robotcode[all]>=2.9.0.dev115"

Using rf-mcp 0.36.x or earlier? Install it as a tool and register it with your coding agents:

uv tool install "rf-mcp[all]==0.36.*"
robotmcp install          # or: claude mcp add rf-mcp -- uvx "rf-mcp[all]==0.36.*"

The full 0.36 documentation is at the v0.36.0 tag.

rf-mcp is a lean, customizable Model Context Protocol (MCP) server built on RobotCode (>=2.9.0.dev115) CLI, robotcode session, and FastMCP Skills over MCP (SEP-2640).

It empowers coding agents (Claude Code, OpenAI Codex, Google Antigravity (agy), GitHub Copilot, OpenCode) to discover, analyze, document, author (repl), debug (robot-debug), execute, and maintain Robot Framework tests and tasks across local machines, remote test runners, zero-daemon remote MCP setups, and CI pipelines.


Key Capabilities

  1. 8 Focused robotcode-Powered MCP Tools:

    • rf_discover: Project suite, test, task, tag, file, test metadata (--values), profile (profiles show for a profile's effective settings), and merged robot.toml discovery (robotcode -f json discover|config|profiles), with --search and a compact longname / source:line / tags projection (verbose=true for full items).

    • rf_analyze: Millisecond headless LSP semantic static analysis (robotcode -r <root> -f json analyze code).

    • rf_doc: Project-aware library, .resource, and keyword documentation (robotcode -f json doc {lib|keywords|keyword}).

    • rf_run: Scoped test/task execution (robotcode robot, supporting -bl <longname>, -btm <metadata>, --rpa, -p <profile>, --wrapper, and inline file synchronization for remote test runners).

    • rf_results: Server-side querying, diffing and merging of output.xml / output.json (robotcode -f json results {summary|show|log|stats|diff} with --search, --sort, --level, --max-depth, --by, --extract screenshot extraction, and rebot --merge). Result files are chosen only with output_path.

    • rf_repl: Stateful multi-turn interactive exploration and test authoring (start, send, wait, status, result, interrupt, list, save, stop) backed by robotcode -f json session (session start repl, .save -t "Name" file.robot, and native Browser.Get Aria Snapshot); edited libraries load after stop and a new start.

    • rf_debug: Stateful multi-turn live test debugger (start, send, wait, status, result, interrupt, list, stop) backed by robotcode -f json session (session start debug, pausing on uncaught failures or --break file.robot:line, preserving output.xml via --output NONE --log NONE --report NONE, and inspecting .where, .vars --user, .list).

    • rf_diagnose: Ranked, library-aware error recovery hinting (Browser, Selenium, Appium, Requests, PlatynUI, BuiltIn, REPL syntax) extensible via <workspace>/.robotframework/hints.toml.

  2. 3 Execution Topologies (server, client, and CI) — Zero Extra Client Daemons:

    • Mode 1: Full Local (--mode server, stdio or http): rf-mcp runs locally alongside your project and executes robotcode and robotcode session directly.

    • Mode 2: Remote Test Runner (--mode server --transport http): rf-mcp and robotcode run on a remote test container/VM (with browsers/devices/displays), accepting inline files synchronization from the coding agent.

    • Mode 3: Zero-Daemon Remote MCP + Local robotcode (--mode client --transport http): rf-mcp runs remotely while the coding agent and robotcode run on the developer's machine. rf-mcp serves project/ecosystem skills over MCP, synthesizes shell-safe local robotcode & robotcode session commands for PowerShell and Bash, and diagnoses failures via rf_diagnose. The agent's root is passed to robotcode -r verbatim (it is a path on the client machine); without one, -r is omitted. rf_debug start also returns a one-shot fallback_command for agent shells that kill background processes; rf_repl has none, because a one-shot REPL cannot replay earlier turns.

    Client-mode commands are executed by a test in both supported shells: PowerShell 7+ and bash. Windows PowerShell 5.1 is untested (its quoting of native arguments differs). Commands set PYTHONUTF8=1, PYTHONIOENCODING=utf-8 and ROBOTCODE_FORCE_AI_AGENT=1.

  3. Skills over MCP (SEP-2640 + ResourcesAsTools) & Plugin Coexistence:

    • Serves layered SKILL.md directories over MCP (skill://{name}/SKILL.md + list_resources / read_resource tools for tool-only agents):

      1. Project-local <workspace>/.robotframework/skills/

      2. External plugin directories via --skills-dir / RF_MCP_SKILLS_DIR, for example a clone or company mirror of MarketSquare/robotframework-plugins

      3. The official Robot Framework skills from robotframework-plugins, installed with rf-mcp

      4. Built-in skills: rf-robotcode (tool routing, triage, debugging, REPL authoring, results, analysis, configuration; maps the upstream robotcode practices P1-P46), rf-locators (Browser, SeleniumLibrary, AppiumLibrary and PlatynUI locators, shadow DOM and iframes, keyword per intent, library chooser) and rf-requests (RequestsLibrary for REST, SOAP/XML and GraphQL). Detail lives in references/ files, e.g. skill://rf-robotcode/references/triage.md.

    • The server instructions are a short intent routing table plus the authoring loop and its finish condition (done only when rf_analyze is clean and rf_run passes).

  4. OpenTelemetry Observability:

    • Built-in child spans (rf_mcp.discover, rf_mcp.analyze, rf_mcp.doc, rf_mcp.run, rf_mcp.results, rf_mcp.repl, rf_mcp.debug, rf_mcp.diagnose) nested under FastMCP server spans, plus metrics (rf_mcp.commands.total, rf_mcp.command.duration_ms, rf_mcp.hints.generated, rf_mcp.skills.read, rf_mcp.skills.pointed).


Related MCP server: Robot Framework MCP Server

Installation & Quick Start

rf-mcp needs Python 3.10+ and uv 0.12 or newer (uv self update). It runs robotcode[all]>=2.9.0.dev115 (currently a pre-release) in your project's own environment, so it sees the libraries and robot.toml your tests use. Older uv versions (0.9 is confirmed) refuse robotcode's pre-release sub-packages during the install unless --prerelease=allow is passed.

rf-mcp installs the official Robot Framework skills with it: the robotframework-plugins package (5.0.0 or newer). Its skills for Browser, SeleniumLibrary, RequestsLibrary, AppiumLibrary and PlatynUI are served over MCP, and the ones that match your project's libraries are attached to the agent's first tool result. To get newer skills without a new rf-mcp release, run uv tool upgrade rf-mcp. To pin them, run uv tool install rf-mcp --with robotframework-plugins==<version>. To follow the repository between releases, set a channel such as stable with rf-mcp init --official-skills stable and fetch it with rf-mcp update-skills --ref stable (RF_MCP_OFFICIAL_SKILLS; see Newer official skills).

uv tool install rf-mcp
rf-mcp init --scope user --agent all --write   # registers `rf-mcp` with each installed agent, for every project

Open any Robot Framework project in your agent and the tools work there: rf-mcp finds the project root from the folder the agent starts it in and runs robotcode with the project's .venv. A project needs only Robot Framework and its libraries; when its environment has no robotcode (or an older one), rf-mcp adds its own robotcode version through uv without changing the project. See Which Python runs your tests.

Option B: install into the project

uv add --dev rf-mcp "robotcode[all]>=2.9.0.dev115"
rf-mcp init --agent all --write                 # writes .mcp.json, .codex/config.toml, .vscode/mcp.json, ...

The project files init writes start uv run rf-mcp and contain no paths, so they can be committed and work in every clone. With pip: pip install rf-mcp "robotcode[all]>=2.9.0.dev115". Name robotcode with its pre-release version as shown: --prerelease=allow or pip --pre would also pull pre-releases of every other dependency (for example FastMCP alphas).

Check and customize

rf-mcp doctor                                   # which root and environment a project gets, robotcode, skills, hints
rf-mcp init --agent claude --url http://mcp.internal:8000/mcp --write   # connect to a remote server instead
rf-mcp sync-skills --agent claude               # copy the skills into .claude/skills (or .agents/skills)

init without --write prints what it would change. It replaces only its own rf-mcp entry in existing files; a file with comments (common in VS Code) is left alone and the entry is printed to paste. With --scope user it uses each agent's own command (claude mcp add --scope user, codex mcp add, copilot mcp add, code --add-mcp, agy mcp add, opencode mcp add --global). sync-skills leaves an existing skill folder alone when its content differs (exit code 1, listed under skipped); pass --force to overwrite it.


Running rf-mcp

# Mode 1: Local stdio MCP server (default); the agent starts it in the project
rf-mcp                                          # optional: -r /path/to/project pins the root, -p ci a profile

# Mode 2: Remote Test Runner over Streamable HTTP
rf-mcp --mode server --transport http --host 0.0.0.0 --port 8000 -r /workspace

# Mode 3: Zero-Daemon Remote MCP Server (synthesizes client-side robotcode commands)
rf-mcp --mode client --transport http --host 0.0.0.0 --port 8000 \
  --skills-dir /opt/robotframework-plugins   # optional: a clone of MarketSquare/robotframework-plugins

Docker

The images run Mode 2 with Browser, SeleniumLibrary and RequestsLibrary installed; rf-mcp-vnc adds a display you can watch in the browser. Mount the project at /workspace:

docker run --rm --shm-size=1g -p 8000:8000 -v "$PWD:/workspace" ghcr.io/manykarim/rf-mcp
rf-mcp init --agent claude --url http://localhost:8000/mcp --write

See docs/DOCKER.md for the VNC image and for building with other libraries.


Project Customization (Zero Code Required)

1. Project Skills (<workspace>/.robotframework/skills/)

Create <workspace>/.robotframework/skills/<skill-name>/SKILL.md to teach connected agents your project's custom libraries, page object patterns, and naming rules. rf-mcp automatically discovers and hot-reloads it at skill://<skill-name>/SKILL.md.

2. Custom Error Recovery Hints (<workspace>/.robotframework/hints.toml)

Define project-specific error recovery hints in .robotframework/hints.toml:

[[hints]]
id = "corp-sso-expired"
title = "Corporate SSO token expired"
error_pattern = "401 Unauthorized.*SSO"
keyword_pattern = ".*"
message = "Refresh the session token using the Auth resource before calling the endpoint."
fix_examples = [
    "Import Resource    resources/auth.resource",
    "Refresh SSO Token",
]
relevance = 99
applies_to = ["runtime", "static"]  # default; "static" = rf_analyze diagnostics

A file that does not parse, or a rule with an invalid regular expression, is skipped with a warning naming the file, line and rule id; the valid rules and all built-in rules stay active. rf-mcp doctor and the server instructions report the skipped entries.

3. Verified cookbook snippets

Every snippet in the built-in rf-locators shadow DOM / iframe reference and in rf-requests is executed by tests/test_cookbook.py (suites in tests/cookbook/) against local fixtures: a widget page with open, nested and closed shadow roots and same-origin, nested, cross-origin and shadow-hosted iframes (tests/fixtures/web/), and a strict REST/SOAP/GraphQL "ledger" API (tests/fixtures/ledger/). The suites need libraries rf-mcp does not depend on and are skipped unless available:

RF_MCP_COOKBOOK_PYTHON=/path/to/venv-with-requests-browser-selenium/python \
RF_MCP_FIXTURE_PYTHON=/path/to/venv-with-fastapi-uvicorn-strawberry/python \
uv run pytest tests/test_cookbook.py

4. OpenTelemetry Export

Install rf-mcp[otel] and pass --otel-endpoint http://localhost:4318 (or set OTEL_EXPORTER_OTLP_ENDPOINT) to export traces and metrics over OTLP.


Documentation

Documentation for rf-mcp 0.36 and earlier is at the v0.36.0 tag.

Available Tools

19 tools
analyze_scenarioA

Analyze a natural-language scenario into structured intent and create a session.

WORKFLOW: This is the single front door — your FIRST tool call for any test scenario. It CREATES the session, so do NOT also call manage_session(action="init") for the same scenario (that causes redundant session churn). Reuse the returned session_id in every later call.

What this tool does:

  1. Creates a new session with unique session_id (or reuses provided one)

  2. Analyzes scenario to detect context (web/api/mobile/desktop)

  3. Auto-configures libraries based on scenario text

  4. Returns session_id for use in ALL subsequent tool calls

CRITICAL: Save the session_id from the response and use it in all other tool calls.

Inputs: scenario (required), context, session_id. Returns: object

build_test_suiteC

Generate a Robot Framework test suite from previously executed steps.

Inputs: test_name (required), tags, bdd_style, session_id, +5 more. Returns: object

check_library_availabilityA

Verify that specified Robot Framework libraries can be imported/installed.

Recommended as step 3 after analyze_scenario and recommend_libraries; use the recommended names to avoid unnecessary checks.

Inputs: libraries (required). Returns: object

execute_batchA

Execute multiple RF keywords in one call with recovery and variable chaining.

Reduces N MCP round-trips to 1. Steps run sequentially; each step's return value is available to later steps via ${STEP_N} references in arguments. Both 0-based (${STEP_0} = first step) and 1-based (${STEP_1} = first step) indexing are accepted. When ambiguous, 1-based is preferred.

Inputs: steps (required), session_id (required), on_failure, timeout_ms, +1 more. Returns: object

execute_flowC

Execute structured flow (if/for/try) within a session.

Inputs: structure (required), session_id (required), items, rethrow, +10 more. Returns: object

execute_stepB

Execute a single Robot Framework keyword (or Evaluate) within a session.

Inputs: keyword (required), mode, record, arguments, +11 more. Returns: object

find_keywordsA

Discover Robot Framework keywords using multiple strategies.

WHEN TO USE THIS TOOL:

  • ALWAYS before calling execute_step with an unfamiliar keyword

  • When you're unsure of exact keyword name or spelling

  • To discover what keywords are available in imported libraries

  • When error says "No keyword with name 'X' found"

Inputs: query (required), limit, context, strategy, +4 more. Returns: object

get_keyword_infoA

Get keyword/library docs or parse a signature. Call this before execute_step when you know the keyword name but not its arguments.

Modes: "keyword" (default — document one keyword), "library" (list a library's keywords), "session" (resolve against the live session namespace), "parse" (parse a signature string). Pass session_id to scope the lookup to that session's libraries.

Inputs: mode, arguments, session_id, keyword_name, +1 more. Returns: object

get_locator_guidanceA

Provide locator/selector guidance for Browser, SeleniumLibrary, AppiumLibrary, PlatynUI.BareMetal, or RequestsLibrary.

For API testing, call with library="requests" (or "api") to get a RequestsLibrary request/response cookbook — session setup, response-field access (${resp.json()["field"]}), the $resp-in-Evaluate rule, Status Should Be, JSON body/headers, the Cookie token header, and expected_status= for non-2xx — BEFORE writing Evaluate-based assertions.

For VISUAL validation, call with library="visual" (or "screenshot") to learn WHEN a screenshot beats the DOM/ARIA tree (canvas/image text, layout/overlap, obscured elements, color, charts) and the dual read-back pattern — useful for any UI library (Browser/Selenium/Appium/PlatynUI) when a multimodal model drives rf-mcp.

Inputs: library, keyword_name, error_message. Returns: object

get_session_stateC

Retrieve aggregated session state for debugging and visibility.

Inputs: session_id (required), mode, sections, state_type, +7 more. Returns: object

intent_actionA

Execute a high-level intent that auto-resolves to the correct library keyword.

Valid intents: navigate, click, fill, hover, select, assert_visible, extract, wait_for.

Also accepted but DEPRECATED:

  • extract_text — equivalent to extract with mode="text". The extract verb is the canonical mode-aware getter (text / attribute / count / value / url / title) and additionally surfaces extracted_value at the top level of the response. extract_text will be removed in a future release; prefer intent="extract" for new code.

The intent is resolved based on the session's active library (Browser/SeleniumLibrary/AppiumLibrary).

Inputs: intent (required), nth, mode, force, +9 more. Returns: object

manage_attachC

Inspect or control attach bridge configuration.

Inputs: action. Returns: object

manage_library_pluginsC

Inspect or reload library plugins.

Inputs: action, plugin_name. Returns: object

manage_sessionA

Manage session lifecycle: initialize, configure libraries/variables, and organize tests.

For a NEW scenario, prefer analyze_scenario — it is the front door that CREATES the session (and auto-configures libraries). Use manage_session for explicit session ops on an existing session (importing extra libraries/resources/variables, multi-test structure). Do NOT call action="init" right after analyze_scenario — the session already exists; that only causes redundant churn.

Workflows: Single test: analyze_scenario -> execute_step (repeat) -> build_test_suite Multi-test: analyze_scenario -> set_suite_setup -> start_test -> execute_step (repeat) -> end_test -> start_test -> ... -> build_test_suite (action="init" is the explicit alternative when you are NOT starting from analyze_scenario, e.g. driving a bare session directly.)

Actions and parameters (session_id is always required):

init             - Create session and load libraries (explicit entry; for a new
                   scenario prefer analyze_scenario instead).
                   Params: libraries (list of library names),
                           variables (dict or list to pre-set).

import_library   - Add a library to an existing session.
                   Params: library_name, args (constructor args), alias.

import_resource  - Import a Robot Framework resource file.
                   Params: resource_path, args.

set_variables    - Set variables in the session.
                   Params: variables (dict {"NAME": "value"} or list ["NAME=value"]),
                           scope ("test" | "suite" | "global", default "suite").

import_variables - Load variables from a Python variable file.
                   Params: variable_file_path, args (passed to get_variables()).

start_test       - Begin a named test (enables multi-test mode). Local mode only.
                   Params: test_name (required),
                           test_documentation, test_tags,
                           test_setup (dict {"keyword": "...", "arguments": [...]}),
                           test_teardown (same format as test_setup).
                   Alias: start_task.

end_test         - End the current test. Local mode only.
                   Params: test_status ("pass" or "fail", default "pass"),
                           test_message (optional error description).
                   NOTE: test_status and test_message are session tracking metadata.
                   They do NOT affect the .robot file generated by build_test_suite.
                   Alias: end_task.

add_data_row     - Add a data row to the current data-driven (template) test.
                   Requires an active test with template set via start_test.
                   Params: args (list of values matching the template keyword's [Arguments]).
                   Alias: data_row.
                   Example:
                     manage_session(action="start_test", test_name="Cart Test",
                                  template="Add And Verify Product")
                     manage_session(action="add_data_row", args=["Backpack", "1", "$29.99"])
                     manage_session(action="add_data_row", args=["Bike Light", "2", "$39.98"])
                     manage_session(action="end_test")
                   The data rows appear under [Template] in the generated .robot file.

list_tests       - List all tests in the session with their status and step counts.
                   Params: (none).

set_suite_setup    - Set a suite-level setup keyword (appears in *** Settings ***).
                     Params: keyword (required), args (keyword arguments).

set_suite_teardown - Set a suite-level teardown keyword (appears in *** Settings ***).
                     Params: keyword (required), args (keyword arguments).

Returns: Dict with success, session_id, and action-specific details. On failure: error and guidance fields are present.

Examples: Initialize session with libraries: manage_session(action="init", session_id="s1", libraries=["Browser", "BuiltIn", "Collections"])

Set suite-level variables:
    manage_session(action="set_variables", session_id="s1",
                   variables={"BASE_URL": "https://example.com", "TIMEOUT": "30"})

Import a library with constructor arguments:
    manage_session(action="import_library", session_id="s1",
                   library_name="Browser", args=["chromium"])

Load a Python variable file:
    manage_session(action="import_variables", session_id="s1",
                   variable_file_path="config/variables.py",
                   args=["production", "secret_key"])

Start a named test (multi-test mode):
    manage_session(action="start_test", session_id="s1",
                   test_name="Login Test", test_tags=["smoke"],
                   test_setup={"keyword": "Open Browser", "arguments": ["chromium"]})

End the current test:
    manage_session(action="end_test", session_id="s1")

Set suite setup (for generated .robot file):
    manage_session(action="set_suite_setup", session_id="s1",
                   keyword="New Browser", args=["chromium"])

Set suite teardown:
    manage_session(action="set_suite_teardown", session_id="s1",
                   keyword="Close Browser")

Inputs: action (required), args, alias, scope, +20 more. Returns: object

recommend_librariesA

Recommend libraries for a scenario or generate/merge sampling prompts.

WHEN TO USE THIS TOOL:

  • IMMEDIATELY after analyze_scenario, before execute_step

  • When you encounter "No keyword with name" errors

  • To discover which libraries provide needed functionality

This tool analyzes scenario text and suggests relevant libraries, saving you from guessing which libraries to import.

Inputs: scenario (required), k, mode, context, +8 more. Returns: object

resume_batchA

Resume a failed batch from its failure point, optionally inserting fix steps.

After execute_batch returns status=FAIL with a batch_id, call this to:

  1. Re-run the failed step (with optional fix_steps injected before it)

  2. Continue executing remaining steps from the original batch

Inputs: batch_id (required), fix_steps, timeout_ms. Returns: object

run_test_suiteB

Validate or execute a Robot Framework suite.

Inputs: mode, session_id, output_level, suite_file_path, +4 more. Returns: object

set_library_search_orderC

Set explicit library search order for keyword resolution.

Inputs: libraries (required), session_id. Returns: object

visual_checkA

Capture a screenshot of the current UI for VISUAL validation (change: visual-inspection-guidance).

Token-cheap by DEFAULT: saves the screenshot to disk and returns the PATH as text — a multimodal agent WITH file access reads that file on demand for checks the DOM/ARIA can't do (canvas/image text, layout/overlap, obscured elements, color, charts). Call get_locator_guidance(library="visual") for when to use it.

Set return_image=true ONLY if your model is multimodal AND cannot read the saved file (e.g. a hosted/remote MCP): the response then includes an image content block. This requires ROBOTMCP_SCREENSHOT_MODE to allow images (image|auto); text-only deployments (mode=file, the default) always return just the path so a text-only model is never sent unsupported image content.

Works across Browser/SeleniumLibrary/AppiumLibrary/PlatynUI (uses the session's screenshot keyword). Degrades cleanly if capture fails.

Inputs: session_id (required), filename, return_image.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 19 tools

    Disambiguation3/5

    Several tools overlap in purpose: execute_batch, execute_step, execute_flow, and run_test_suite all execute Robot Framework code, and find_keywords vs get_keyword_info both serve keyword discovery. The detailed descriptions clarify boundaries, but an agent could still misselect between execution tools or keyword-lookup tools without careful reading.

    Naming Consistency4/5

    Most tools follow a clear verb_noun snake_case pattern (execute_batch, manage_session, build_test_suite). A few deviate: intent_action is noun_verb, visual_check is adjective_verb, and manage_attach is vague. Overall the pattern is predictable with minor inconsistencies.

    Tool Count3/5

    With 19 tools, this exceeds the ideal 3-15 range but is not excessive for a comprehensive Robot Framework automation server. The count is justified by the breadth of functionality (session management, keyword discovery, execution, suite building, visual checks), but it feels slightly heavy.

    Completeness4/5

    The tool surface covers the full lifecycle from scenario analysis (analyze_scenario) through keyword discovery and execution (execute_step/batch/flow) to suite generation (build_test_suite) and validation (run_test_suite). Minor gaps exist, such as explicit test result retrieval or test data management, but the core workflows are well-covered.

    Maintenance

    ActivityMaintained
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A comprehensive Model Context Protocol (MCP) server suite that enables AI coding agents to automate both web browsers and Electron desktop applications with auto-snapshots and element references.
      61
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      A universal AI-powered testing server built on the Model Context Protocol (MCP). Allows AI agents to inspect, execute, test, monitor, debug, and report on software projects.
      3
      GNU Lesser General Public v2.1 only