mockd

One binary. Seven protocols. Zero dependencies.

Mock HTTP, gRPC, GraphQL, WebSocket, MQTT, SSE, and SOAP APIs from a single CLI tool. Import from OpenAPI, Postman, WireMock, HAR, or cURL. Share mocks instantly via built-in cloud tunneling.

Why mockd?

Install

# Quick install
curl -sSL https://get.mockd.io | sh

# Homebrew
brew install getmockd/tap/mockd

# Docker
docker run -p 4280:4280 -p 4290:4290 ghcr.io/getmockd/mockd:latest

# Go
go install github.com/getmockd/mockd/cmd/mockd@latest

Pre-built binaries for Linux, macOS, and Windows are available on the Releases page.

Quick Start

# Start the mock server
mockd start

# Mock an HTTP endpoint
mockd add http --path /api/users --body '[{"id": 1, "name": "Alice"}]'

# Test it
curl http://localhost:4280/api/users
# → [{"id": 1, "name": "Alice"}]

# Mock a GraphQL API
mockd add graphql --path /graphql --operation users \
  --response '[{"id": 1, "name": "Alice"}]'

# Mock a gRPC service
mockd add grpc --proto ./service.proto \
  --service myapp.UserService --rpc-method GetUser \
  --response '{"id": 1, "name": "Alice"}'

# Mock a WebSocket endpoint
mockd add websocket --path /ws/chat --echo

# Import from OpenAPI, Postman, or cURL
mockd import openapi.yaml
mockd import collection.json
mockd import "curl -X GET https://api.example.com/users"

Features

Multi-Protocol Mocking

Mock seven protocols from a single tool with a unified CLI and Admin API:

Import & Export

Bring your existing API definitions — no rewriting needed:

mockd import openapi.yaml           # OpenAPI 3.x / Swagger 2.0
mockd import collection.json        # Postman collections
mockd import recording.har          # HAR files
mockd import wiremock-mapping.json  # WireMock stubs
mockd import service.wsdl           # WSDL → SOAP mocks
mockd import "curl -X GET https://api.example.com/users"  # cURL commands
mockd export --format yaml > mocks.yaml

Cloud Tunnel

Share local mocks with your team instantly. All protocols routed through a single QUIC connection on port 443:

mockd tunnel enable
# → https://a1b2c3d4.tunnel.mockd.io → http://localhost:4280

Chaos Engineering

Test how your app handles failures:

# Apply a built-in chaos profile at startup
mockd serve --chaos-profile flaky --config mockd.yaml

# Or enable chaos at runtime
mockd chaos apply slow-api

Stateful Mocking

Simulate CRUD resources with automatic ID generation, pagination, and persistence. State is shared across protocols — REST and SOAP operate on the same data:

# mockd.yaml
statefulResources:
  - name: users
    basePath: /api/users
    seedData:
      - { id: "1", name: "Alice", email: "alice@example.com" }

mocks:
  - type: soap
    soap:
      path: /soap/UserService
      operations:
        GetUser:
          statefulResource: users    # Same data as REST!
          statefulAction: get

mockd serve --config mockd.yaml

# Create via REST
curl -X POST http://localhost:4280/api/users \
  -d '{"name": "Bob"}' -H 'Content-Type: application/json'

# Retrieve via SOAP — same user!
curl -X POST http://localhost:4280/soap/UserService \
  -H 'SOAPAction: GetUser' -H 'Content-Type: text/xml' \
  -d '<soap:Envelope>...<GetUser><Id>...</Id></GetUser>...</soap:Envelope>'

Proxy Recording

Record real API traffic and replay it as mocks:

mockd proxy start --port 8888
# Configure your app to use http://localhost:8888 as proxy
# Traffic is recorded, then replay with:
mockd import recordings/session-name.json

Admin API

Full REST API for dynamic mock management at runtime:

# Create a mock
curl -X POST http://localhost:4290/mocks \
  -H "Content-Type: application/json" \
  -d '{"type":"http","http":{"matcher":{"method":"GET","path":"/health"},"response":{"statusCode":200,"body":"{\"status\":\"ok\"}"}}}'

# List mocks
curl http://localhost:4290/mocks

# Import OpenAPI spec
curl -X POST http://localhost:4290/import \
  -H "Content-Type: application/x-yaml" \
  --data-binary @openapi.yaml

AI Mock Generation (MCP)

mockd includes a built-in Model Context Protocol server with 16 tools for full mock lifecycle management from AI-powered editors (Cursor, Windsurf, Claude Code):

mockd mcp  # Start the MCP server (stdio transport)

Tools cover mock CRUD, import/export, chaos engineering (10 built-in profiles), mock verification, stateful resource management, custom operations, and multi-environment context switching.

Configuration

Configure via flags, environment variables, or config files:

# .mockdrc.yaml
port: 4280
adminPort: 4290
httpsPort: 5280
maxLogEntries: 1000

Documentation

mockd.io — Full documentation, guides, and API reference.

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

Apache License 2.0