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.

Package

@erivelto_muller/wiremock-mcp

The package is published to the public npm registry.

MVP architecture

Codex / Claude / Cursor / MCP client
                 |
                 | MCP stdio
                 v
       @erivelto_muller/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

• 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", "@erivelto_muller/wiremock-mcp"],
      "env": {
        "WIREMOCK_URL": "http://localhost:8080"
      }
    }
  }
}

For an existing WireMock on another port:

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

The server can also be started directly:

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

No repository clone is required for normal use.

Tools

The server exposes the following MCP tools:

| Tool | Purpose | |---|---| | wiremock_status | Check connectivity, health and WireMock version | | mock_list | List registered stub mappings | | mock_get | Get one mapping by ID | | mock_create | Create a WireMock mapping | | mock_update | Update a mapping by ID, enforcing namespace ownership when configured | | mock_delete | Delete a mapping by ID, enforcing namespace ownership when configured | | mock_adopt | Explicitly adopt an unmanaged legacy mapping into the current namespace | | mock_delete_owned | Delete only mappings owned by the current namespace | | mock_reset | Reset runtime mappings to the backing-store defaults | | request_list | List requests from the request journal | | request_get | Get one journal request by ID | | request_unmatched | List requests that matched no stub | | request_count | Count journal requests matching a WireMock request pattern | | request_clear | Clear the request journal without deleting mappings |

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

Namespace ownership

By default the server runs in unscoped compatibility mode. This keeps existing WireMock workflows working: mappings are not automatically tagged, and mock_update, mock_delete, mock_reset and request_clear behave globally.

For multi-agent use, run one MCP process per agent with a distinct namespace:

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

When WIREMOCK_MCP_NAMESPACE is set, mappings created by this MCP process are tagged in WireMock metadata:

{
  "metadata": {
    "wiremockMcp": {
      "managed": true,
      "namespace": "agent-a"
    }
  }
}

The reserved key is metadata.wiremockMcp. Other metadata is preserved.

Ownership classifications:

| Classification | Meaning | |---|---| | OWNED | Managed by this MCP process namespace | | FOREIGN | Managed by another MCP namespace | | UNMANAGED | No valid WireMock MCP ownership metadata | | UNSCOPED | No namespace configured, compatibility mode |

Reads are never blocked by ownership. Agents can still list and inspect foreign or unmanaged mappings for diagnosis.

Writes are guarded when namespace mode is active:

• mock_update and mock_delete allow OWNED mappings;
• FOREIGN mappings are always refused;
• UNMANAGED mappings are refused by default;
• pass allowUnmanaged: true to mock_update or mock_delete for an explicit opt-in operation on a legacy mapping.

allowUnmanaged does not adopt a mapping. To mark a legacy mapping as owned by the current namespace, use:

mock_adopt(id="...")

mock_adopt is idempotent for OWNED mappings, refuses FOREIGN mappings and preserves request/response fields plus non-reserved metadata.

To clean up only this namespace, use:

mock_delete_owned()

mock_delete_owned does not remove foreign or unmanaged mappings.

mock_reset and request_clear are global operations. When namespace mode is active, both are blocked by default. You can explicitly allow them for a process:

{
  "mcpServers": {
    "wiremock-agent-a": {
      "command": "npx",
      "args": ["-y", "@erivelto_muller/wiremock-mcp"],
      "env": {
        "WIREMOCK_URL": "http://localhost:8080",
        "WIREMOCK_MCP_NAMESPACE": "agent-a",
        "WIREMOCK_MCP_ALLOW_GLOBAL_DESTRUCTIVE": "true"
      }
    }
  }
}

Only enable this for isolated WireMock instances or when the agent is expected to affect every mapping/request journal entry in the configured WireMock. Request journal ownership is not tracked in this version.

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_delete_owned removes all mappings owned by the current namespace;
• 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:

@erivelto_muller/wiremock-mcp

Releases are intended to be published by GitHub Actions from SemVer tags after Trusted Publishing is configured on npmjs.com.

Manual publishing, when needed, uses:

npm publish --access public

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

CI and releases

Continuous integration runs on pushes and pull requests to master:

• npm ci
• npm run typecheck
• npm run build
• npm test
• npm run test:integration
• npm pack --dry-run

The publish workflow runs only when a tag matching v* is pushed. Before publishing, it repeats the same gates and verifies that the tag version matches package.json exactly:

v0.2.0 -> package.json version 0.2.0

The workflow uses npm Trusted Publishing with GitHub Actions OIDC. It does not use long-lived npm publish tokens, publish secrets or OTP values.

After .github/workflows/publish.yml exists on the default branch, the maintainer must configure the npm package Trusted Publisher with:

Provider: GitHub Actions
GitHub user/org: Erivelto47
Repository: wiremock-mcp
Workflow filename: publish.yml
Allowed action: npm publish
Environment: empty

The workflow filename is publish.yml, not .github/workflows/publish.yml. Each npm package supports one Trusted Publisher at a time. Do not create a release tag until this npm package setting has been configured.

Roadmap

MVP — one external WireMock

• TypeScript / Node.js
• MCP over stdio
• one WIREMOCK_URL
• mapping CRUD
• namespace ownership for concurrent agents
• request-journal inspection
• npm distribution
• CI and Trusted Publishing workflow
• 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
• per-namespace request-journal isolation

These are not part of the MVP.

License

MIT. See LICENSE.