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

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.