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

1. Fork this repo
2. Create a feature branch
3. Submit a Pull Request

---

📜 License

See LICENSE file for licensing terms.