Skip to main content
MCP server CX Codex

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 GitHub

What 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.

Similar MCP servers

All MCP servers for Backend and APIs →

Project sponsors

Companies that keep this analytics open