hoverfly
Hoverfly MCP Server is a Spring Boot app that exposes Hoverfly via the Model Context Protocol (MCP), enabling AI assistants like Cursor or Copilot to manage mock APIs automatically. It helps simulate unavailable APIs with simple JSON, supporting full mock lifecycle control.
claude mcp add --transport stdio kapishmalik-hoverfly-mcp-server docker 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
How to use
This MCP server exposes Hoverfly as a programmable tool that AI assistants can use to dynamically mock third-party APIs. By running the server in Docker, you provide a persistent simulation directory at /opt/hoverfly-mcp/simulation-data where Hoverfly can store and load simulations. The server offers a suite of tools (get_hoverfly_status, start_hoverfly_web_server, add_hoverfly_mock, etc.) that can be invoked by your MCP-enabled assistant to manage mocks, retrieve documentation, and fetch debug logs. You can use these tools to start a web server that serves Hoverfly in simulate mode, load the most recent simulation by default, and then create, list, or remove mocks as your integration tests run.
How to install
Prerequisites (for building from source):
- Java 17
- Maven 3.6+
Build and run from source:
- git clone <repository-url>
- cd hoverfly-mcp-server
- mvn clean package
- java -jar target/hoverfly-mcp-server-<version>.jar
If you prefer using the provided Docker image (recommended for most users):
- Ensure Docker is installed and running
- Run the following (as described in the MCP config):
# Use the docker-based MCP server configuration as described in mcp_config
Note: The Docker-based setup maps ports 8500 (Hoverfly proxy) and 8888 (Hoverfly admin) and mounts a persistence directory to /opt/hoverfly-mcp/simulation-data.
Additional notes
Tips and notes:
- Docker is the easiest path for most users; it automatically pulls the image if not present locally.
- The simulation data directory mounted to /opt/hoverfly-mcp/simulation-data is the only supported location for persistent data; ensure the host directory is writable by the container user.
- Auto-load behavior loads the most recent simulation on startup unless disabled via configuration.
- Use the provided MCP tools to manage mocks, fetch documentation, and view debug logs to troubleshoot issues with endpoints or simulations.
