Hoverfly — Claude Code MCP server: features and setup
This MCP server lets an AI assistant control Hoverfly mocks. Use it to test API integrations when an external service is unavailable.
no license updated 2026-10-29
Open on GitHubWhat Hoverfly does
The assistant can start or stop Hoverfly, check its status, inspect active mocks, and add a mock from a JSON request-response pair. Other tools provide Hoverfly documentation, matcher suggestions, endpoint details, and recent logs. This gives the assistant a way to manage simulated API responses during development and testing.
Run the server in Docker. Port 8500 handles the proxy, while 8888 serves the admin API. To keep simulations across container restarts, mount a writable host directory at /opt/hoverfly-mcp/simulation-data; this is the supported location for persistent data. Simulations are saved there when download_hoverfly_simulation is called, and startup can load the latest saved file. Building from source requires Java 17 and Maven 3.6+.
What it helps with
- mock an external API response during development
- create an API mock from a JSON request-response pair
- inspect active Hoverfly mocks
- keep simulation data across container restarts
- retrieve Hoverfly logs while debugging
Example prompts for the agent
- Start Hoverfly in simulation mode and check its status.
- Add an API mock from this JSON request-response pair.
- Save the current Hoverfly simulation to its data directory.
How to install Hoverfly
Install
The MCP registry has no launch command for it: see the repository README
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Hoverfly
How do I install Hoverfly in Claude Code?
Add an MCP server entry to .mcp.json that runs docker with the image docker.io/kapish88/hoverfly-mcp-server. Pass the 8500 and 8888 port mappings, and mount a writable directory at /opt/hoverfly-mcp/simulation-data to retain simulations. Docker must be installed.
What does Hoverfly do?
It exposes Hoverfly controls to an AI assistant over MCP. The assistant can start the server and manage API mocks for integration tests when an external service cannot be reached.
Where does Hoverfly store simulations?
Mount a writable host directory at /opt/hoverfly-mcp/simulation-data inside the container. Simulations are saved there when download_hoverfly_simulation runs, and startup can load the latest saved simulation.