roadtools-mcp

An MCP server for ROADtools. It lets an MCP client (Claude Desktop and others) query the Entra ID / Azure AD data that ROADrecon collects, and optionally run the ROADtools workflow (authenticate, collect, analyze) against a tenant.

Works with ROADrecon 2.0 / roadlib 1.7 and the current mcp SDK.

Only run this against tenants you own or are authorized to test. See SECURITY.md.

Requirements

• Python 3.10+
• mcp and httpx (installed with the package)
• roadrecon and roadtx if you want the database-mode tools, live collection, or roadtx (pip install roadrecon roadtx)
• An MCP client such as Claude Desktop

Installation

pip install "git+https://github.com/websec/ROADtools-MCP.git"
pip install roadrecon roadtx        # optional, for DB mode / collection / roadtx

Or from a clone:

git clone https://github.com/websec/ROADtools-MCP
cd ROADtools-MCP
pip install -e .

This adds a roadtools-mcp command. You can also run the file directly: python roadtools_mcp_server.py.

Claude Desktop

Add the server under mcpServers in claude_desktop_config.json (Settings > Developer > Edit Config):

{
  "mcpServers": {
    "roadtools": {
      "command": "roadtools-mcp",
      "env": {
        "ROADRECON_URL": "http://localhost:5000",
        "ROADRECON_DB": "C:\\path\\to\\roadrecon.db"
      }
    }
  }
}

If roadtools-mcp is not on PATH (Claude Desktop may use a different Python), use "command": "python" with "args": ["C:\\path\\to\\roadtools_mcp_server.py"] instead.

Restart Claude Desktop and run check_connection to verify the connection.

Usage

There are two ways to use it.

1. Against an existing dump. Start the GUI (roadrecon gui -d roadrecon.db), set ROADRECON_URL, and set ROADRECON_DB if you want the database-mode tools. Then ask the client to run the analysis tools (find_privileged_users, analyze_conditional_access, and so on).

2. Collect first, then analyze. Ask the client to run it against a tenant. It uses start_login (device-code sign-in, which handles MFA), start_collection (roadrecon gatherall), and start_gui, then points the analysis tools at the result. Each engagement is kept in its own folder under ROADTOOLS_WORKDIR (default ~/roadtools-engagements).

Configuration

Variable	Default	Purpose
ROADRECON_URL	http://localhost:5000	ROADrecon GUI base URL (API mode)
ROADRECON_DB	unset	Path to roadrecon.db (enables database mode)
ROADRECON_TIMEOUT	60	HTTP timeout in seconds
ROADRECON_MAX_ITEMS	200	Max items returned in a single tool result
ROADTOOLS_WORKDIR	~/roadtools-engagements	Per-engagement tokens, database, exports
ROADRECON_STALE_DEVICE_DAYS	90	Stale-device threshold (database mode)

Tools

Connectivity and retrieval: check_connection, list_capabilities, get_tenant_summary, search_principals, get_user, get_service_principal, get_application, get_group, get_azure_roles_for_principal, get_pim_assignments_for_user, get_conditional_access_for_user.

Analysis (API mode): find_privileged_users, analyze_mfa_status, find_applications_with_secrets, analyze_service_principal_credentials, analyze_groups, identify_stale_accounts, analyze_pim_implementation, analyze_legacy_authentication, find_dangerous_app_permissions, analyze_oauth2_grants, find_privilege_escalation_paths, analyze_guest_access, analyze_devices, analyze_administrative_units.

Analysis (database mode, needs ROADRECON_DB): analyze_azure_rbac, analyze_conditional_access, and analyze_conditional_access_html as a fallback.

Live collection and jobs: roadtools_env, start_login, get_login_status, start_collection, get_collection_status, start_gui, use_engagement, export_data, cleanup_engagement, list_jobs, get_job_output, stop_job.

roadtx: roadtx_help, roadtx_run, roadtx_describe.

Prompts: full_pentest_recon, hunt_azure_rbac_escalation, review_conditional_access_gaps, analyze_security_posture, investigate_application_risks.

Collecting data with ROADtools

roadrecon auth                    # device-code / browser sign-in (handles MFA)
roadrecon gatherall --autotoken   # AAD graph + Identity Governance + PIM + Azure RM
roadrecon gui -d roadrecon.db

You can also run the stages individually (roadrecon dump, azgather, pimgather, iggather).

Background

This started as an update to Max Andreacchi's roadrecon_mcp_server, which exposed ROADrecon over MCP but predated ROADrecon 2.0. Besides updating it for the current ROADrecon and MCP SDK, this version adds:

• Azure RBAC (subscriptions, scope, eligible vs active assignments)
• Conditional Access parsed from the database instead of an exported HTML file
• PIM eligible vs permanent assignments
• Identity Governance access packages and administrative units
• OAuth2 delegated consent and dangerous application-permission checks
• Privilege-escalation hints, external/guest admin flags, device posture
• MFA read from the database (the /api/mfa endpoint drops cloud-only users)
• A direct database mode in addition to the HTTP API
• Live collection and roadtx driven from the client, with per-engagement folders
• Packaging, a test suite and CI

Tests

The tests build a synthetic ROADrecon database, start a GUI against it on a free port, and exercise the tools. No real tenant is used.

pip install -e . && pip install roadrecon roadtx
python tests/import_check.py
python tests/e2e_test.py

Credits

• ROADtools (ROADrecon, roadlib, roadtx) by Dirk-jan Mollema: https://github.com/dirkjanm/ROADtools
• Original ROADrecon MCP by Max Andreacchi
• This version by Joel Aviad Ossi (WebSec)

License

MIT. See LICENSE. ROADtools is separate and under its own license.