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.

🚀 Quick Start

This server is based on Spring Boot and uses the Model Context Protocol (MCP) to expose Hoverfly. It can be used by various AI assistants to dynamically mock third - party APIs, facilitating development and testing when external services are unavailable.

✨ Features

• Exposes Hoverfly as a programmable tool for AI assistants.
• Enables dynamic mocking of third - party APIs.
• Supports simulation persistence.

📦 Installation

⚠️ Important 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

💡 Usage Tip

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

⚠️ Important Note

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.

⚠️ Important 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.