Hoverfly MCP Server
A Model Context Protocol (MCP) server that exposes Hoverfly as a programmable tool for AI assistants like Cursor, Claude, GitHub Copilot, and others supporting MCP. It enables dynamic mocking of third-party APIs to unblock development, automate testing, and simulate unavailable services during integration.
12 Tools
Requires Configuration
Add to Docker Desktop
Version 4.43 or later needs to be installed to add the server automatically
Tools
| Name | Description |
|---|---|
add_hoverfly_mock | Creates a new mock API by adding a request-response pair to Hoverfly's simulation. Make sure to call startHoverfly() first as WebServer. If Hoverfly is not running, this operation will fail. The input must be a valid RequestResponsePair object with request matchers (like path, method, destination, etc.) and a response containing status, body, and headers. |
clear_hoverfly_mocks | Deletes all mock APIs from Hoverfly's simulation. |
download_hoverfly_simulation | Downloads the current Hoverfly simulation file to the persistent simulation directory. The simulation is always saved to /opt/hoverfly-mcp/simulation-data inside the container. Mount this directory to your host for persistence. The file will be saved with a timestamp for easy identification. Use this to persist your mock configurations for later use or sharing. |
fetch_hoverfly_version | Returns the current version of the Hoverfly instance. |
get_hoverfly_debug_logs | # Hoverfly Debug Logs Tool Use this tool to fetch recent logs from the running Hoverfly instance for advanced debugging and troubleshooting. This is especially useful when: - You encounter errors while creating a mock API. - You receive unexpected or incorrect mock responses. - You suspect issues with templating, matcher configuration, or simulation logic. - You want to understand why a request was not matched as expected. ## How to Use - **When:** Use this tool immediately after a failed mock creation, or when you get an unexpected response from a mock API. - **Why:** The logs provide detailed insight into Hoverfly's internal processing, including matcher evaluation, templating errors, and simulation execution. - **What:** The tool returns the latest log entries from the Hoverfly admin API, which can be used to diagnose and resolve issues. ## Parameters - `limit` (optional, default: 500): The maximum number of log entries to fetch. Increase this if you need a longer history. ## Example ```json { "limit": 500 } ``` ## Output - Returns a JSON object containing a list of log entries, each with timestamp, level, and message fields. --- **Tip:** Use this tool as your first step in debugging any Hoverfly simulation or templating issue! |
get_hoverfly_documentation | Returns Hoverfly documentation for a specific topic. Allowed values: `matchers`, `templating`. Helpful for developers or LLMs building or validating simulation JSON. You can also call this tool to get guidance when facing issues with matchers or templating in your simulation definitions. |
get_hoverfly_status | Returns the current status of the Hoverfly server. |
list_hoverfly_mocks | Lists all request-response pairs (mock APIs) currently active in Hoverfly. |
show_hoverfly_endpoints_info | Returns a canonical list of all key Hoverfly endpoints, including: - Mock server base URL (for intercepted API calls) - Admin API and UI (for managing simulations and viewing logs) - Simulation file endpoint (for viewing or downloading the current simulation) - Example curl commands for quick testing This helps developers, tools, or LLMs understand how to interact with Hoverfly after startup. |
start_hoverfly_web_server | Starts the Hoverfly mock server in simulate mode and exposes it on port 8500 for mock server and port 8888 for admin endpoint. Can optionally load simulation from the persistent simulation directory on startup using the loadSimulationOnStartup parameter. If not passed, this parameter defaults to true. The simulation will be loaded from /opt/hoverfly-mcp/simulation-data if available. **Access URLs:** - **Admin UI:** http://localhost:8888 - **Mock Server Endpoint:** http://localhost:8500 - **View or download the current simulation at:** http://localhost:8888/api/v2/simulation You can: - Point your API clients to `http://localhost:8500` |
stop_hoverfly_server | Stops the Hoverfly mock server and clears its state. |
suggest_hoverfly_matchers | Analyzes a single Hoverfly RequestResponsePair JSON and returns matcher suggestions for each request field. The input must be a valid RequestResponsePair object. Each field in the request block will be analyzed and matcher suggestions will be provided. These suggestions can be used to make your matchers more robust and reliable. See the documentation for the expected input format and matcher details. |
Manual installation
You can install the MCP server using:
Installation for