wiremock-mcp

A lightweight MCP server that lets coding agents manage a local or remote WireMock instance through the WireMock Admin API.

The project is designed around a simple rule: WireMock remains the source of truth. The MCP server does not own or migrate your existing mappings; it connects to the WireMock instance you already use.

Status

The first MVP is being prepared. The target package name is:

@erivelto47/wiremock-mcp

The npx examples below will work after the first npm release is published. Until then, use the local development instructions.

Related MCP server: @restforge-dev/mcp-server

MVP architecture

Codex / Claude / Cursor / MCP client
                 |
                 | MCP stdio
                 v
       @erivelto47/wiremock-mcp
                 |
                 | HTTP
                 v
       WIREMOCK_URL/__admin/*
                 |
                 v
             WireMock 3.x

The MVP connects to one WireMock instance configured by WIREMOCK_URL.

Default:

http://localhost:8080

Requirements

For normal use after the npm package is published:

• Node.js 22 or newer

• a running WireMock 3.x instance

• an MCP client with stdio server support

Docker is optional. It is only needed if you want an easy way to start WireMock locally.

Quick start

1. Start WireMock if you do not already have one

Using the official WireMock Docker image:

docker run --rm -it \
  --name wiremock \
  -p 8080:8080 \
  wiremock/wiremock:3.13.2

Verify it:

curl http://localhost:8080/__admin/health

If you already have WireMock running with existing mappings, keep using it. You do not need to migrate them.

2. Configure the MCP server

Generic process-spawned MCP configuration:

{
  "mcpServers": {
    "wiremock": {
      "command": "npx",
      "args": ["-y", "@erivelto47/wiremock-mcp"],
      "env": {
        "WIREMOCK_URL": "http://localhost:8080"
      }
    }
  }
}

For an existing WireMock on another port:

{
  "mcpServers": {
    "wiremock": {
      "command": "npx",
      "args": ["-y", "@erivelto47/wiremock-mcp"],
      "env": {
        "WIREMOCK_URL": "http://localhost:9090"
      }
    }
  }
}

After npm publication, the server can also be started directly:

WIREMOCK_URL=http://localhost:9090 \
npx -y @erivelto47/wiremock-mcp

No repository clone is required for normal use after publication.

MVP tools

The first release targets the following MCP tools:

The create/update/count tools intentionally preserve WireMock's advanced request/mapping structure instead of reducing WireMock to a small custom schema.

Example agent requests

Once the MCP is configured, examples include:

Create a GET /products/123 mock returning HTTP 200 with this JSON body: ...

List the existing WireMock mappings and show me which one handles /payments.

Update this mapping so that it returns HTTP 503 with a 500 ms delay.

Show the requests received by WireMock that did not match any mock.

Check whether my application called POST /orders and how many times.

Existing WireMock environments

Using an existing instance is a primary use case.

For example, if your WireMock already runs at:

http://localhost:9090

with a collection of existing mappings, configure only:

WIREMOCK_URL=http://localhost:9090

The MCP operates on the mappings and request journal already present in that WireMock instance.

Safety

The configured MCP server has permission to modify the WireMock instance pointed to by WIREMOCK_URL.

Some tools are intentionally destructive:

• mock_delete removes a mapping;

• mock_reset resets runtime mappings;

• request_clear clears the request journal.

Use a development/test WireMock instance unless you explicitly intend the agent to manage another environment.

The MVP does not expose WireMock shutdown operations.

The MVP does not implement authentication, credential storage, request redaction, multi-tenant authorization or environment allowlists. If your WireMock Admin API is reachable from this server, an MCP client can create, update and delete mappings and clear the request journal through the tools listed above. Prefer isolated development/test instances and avoid pointing WIREMOCK_URL at shared or production-like environments unless that access is intentional.

HTTPS URLs are accepted, but no custom CA, client certificate or authorization header configuration is included in the MVP.

Development

Clone the repository:

git clone https://github.com/Erivelto47/wiremock-mcp.git
cd wiremock-mcp

Install dependencies:

npm ci

Build:

npm run build

Run the server from a local build:

WIREMOCK_URL=http://localhost:8080 node dist/index.js

Run unit tests:

npm test

Run the real WireMock integration/E2E suite:

npm run test:integration

The integration suite starts an isolated WireMock Docker container on port 18080, exercises the MCP through stdio and cleans the container afterward.

Test the package before publishing

Inspect the files that would be included in the npm package:

npm pack --dry-run

A local tarball can also be generated with:

npm pack

This makes it possible to smoke-test the installable package before publishing it.

npm distribution

The primary distribution target is the public npm registry so users can run the MCP with npx and do not need to clone this repository.

Target package:

@erivelto47/wiremock-mcp

A scoped public package is published with:

npm publish --access public

Publishing is a release-maintainer action and is not performed automatically by normal development/test commands.

Roadmap

MVP — one external WireMock

• TypeScript / Node.js

• MCP over stdio

• one WIREMOCK_URL

• mapping CRUD

• request-journal inspection

• npm distribution

• real WireMock Docker E2E tests

Next functional step — multiple WireMock instances

A later release can support named instances while keeping the current single-URL configuration as the default.

Conceptually:

mock_list(instance="payments")
mock_create(instance="legacy", ...)

Possible configuration:

instances:
  payments: http://localhost:9091
  legacy: http://localhost:9092

This is intentionally outside the first MVP so the initial server stays small and predictable.

Future distribution — all-in-one Docker image

A later release can provide an OCI/Docker image that bundles:

MCP server + WireMock

for zero-config local onboarding.

That convenience image must not remove the ability to connect the MCP to an existing external WireMock instance.

Other possible extensions

• Streamable HTTP transport

• OpenAPI-assisted mock creation

• recording/proxy workflows

• richer request verification helpers

• namespaces/ownership metadata for concurrent agents

These are not part of the MVP.

License

MIT. See LICENSE.