# Hoverfly
Hoverfly MCP Server turns Hoverfly into an AI-controllable HTTP mocking engine via the Model Context Protocol (MCP). It enables developers using AI assistants like Cursor, Claude, and Copilot to create, validate, and manage mock APIs on demand. Useful for simulating flaky or third-party services, it supports matcher suggestions, templating help, log debugging, and live inspection — all triggered through natural language or structured tool use.
README: https://github.com/kapishmalik/hoverfly-mcp-server
Hoverfly MCP Server
A Spring Boot-based Model Context Protocol (MCP) server that exposes Hoverfly as a programmable tool for AI assistants like Cursor, Claude Desktop, GitHub Copilot, or any other assistant supporting MCP. It enables dynamic mocking of third-party APIs to unblock development and testing when external services are unavailable.
🛠️ Installation
Note: The following prerequisites and build steps are only required if you want to contribute or build from source. For most users, using the Docker image is sufficient.
Prerequisites
- Java 17
- Maven 3.6+
Build & Run
git clone <repository-url>
cd hoverfly-mcp-server
mvn clean package
java -jar target/hoverfly-mcp-server-<version>.jar
Replace
<version>with the actual version of the JAR you built.
⚙️ Configuring as an MCP Server (with Docker)
To use this server with an AI assistant that supports Model Context Protocol (MCP), add the following to your .mcp.json or mcp.config.json:
{
"mcpServers": {
"hoverfly-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-p 8500:8500",
"-p 8888:8888",
"-v /path/to/your/data:/opt/hoverfly-mcp/simulation-data",
"docker.io/kapish88/hoverfly-mcp-server"
]
}
}
}
8500: Hoverfly proxy port (mocked services)8888: Hoverfly admin port (mock control API)-v /path/to/your/data:/opt/hoverfly-mcp/simulation-data: Mount a volume for simulation persistence
Make sure Docker is installed. The image will be pulled automatically if not available locally.
🔧 Exposed MCP Tools
| Tool Name | Description |
|---|---|
get_hoverfly_status | Checks if Hoverfly is running |
start_hoverfly_web_server | Starts Hoverfly in simulate mode as a web server. By default, it will auto-load the most recent simulation from /opt/hoverfly-mcp/simulation-data if available, unless auto-load is disabled. |
stop_hoverfly_server | Stops Hoverfly and clears mocks |
fetch_hoverfly_version | Returns Hoverfly version |
list_hoverfly_mocks | Lists all active mock APIs (request-response pairs) |
add_hoverfly_mock | Adds a mock API using a JSON RequestResponsePair definition |
clear_hoverfly_mocks | Removes all existing mock APIs |
show_hoverfly_endpoints_info | Returns key Hoverfly endpoints and example usage |
get_hoverfly_documentation | Returns Hoverfly documentation for a specific topic |
suggest_hoverfly_matchers | Suggests matcher options for a given request-response pair JSON |
get_hoverfly_debug_logs | Fetches recent Hoverfly logs for debugging (limit is optional) |
download_hoverfly_simulation | Downloads current simulation to /opt/hoverfly-mcp/simulation-data (persistent simulation directory) |
These tools can be invoked programmatically by AI assistants through the AI Assistant host.
💾 Simulation Persistence
The server supports simulation persistence through a fixed, mounted volume:
Auto-Load on Startup
When starting Hoverfly with start_hoverfly_web_server, the server will by default:
- Load the most recent simulation file from
/opt/hoverfly-mcp/simulation-data(if available) - Start with a clean state if no simulation file is found
You can disable auto-load by setting the appropriate parameter.
Persistent Data and Volume Mounting
To persist simulation data across restarts, you must mount a host directory to /opt/hoverfly-mcp/simulation-data inside the container.
This is the only supported location for persistent data.
Note: The host directory must be writable by the container user.
Simulation files are only saved to this directory when you explicitly invoke the download tool.
🤝 Contributing
- Fork this repo
- Create a feature branch
- Submit a Pull Request
📜 License
See LICENSE file for licensing terms.
