Mimikos — The Mock Server That Understands Your API

See it in action

Point Mimikos at an OpenAPI spec. It classifies every endpoint automatically:

Classified automatically from the spec alone. 96% accuracy across 344 real-world endpoints — no annotations, no configuration files.

Text version (for screen readers and AI agents)

mimikos start petshop.yaml

🎭 mimikos v0.4.0
Spec: PetShop Pro (OpenAPI 3.0.3)
Operations: 27 endpoints classified

  METHOD  PATH                                  BEHAVIOR   CONFIDENCE
  GET     /pets                                 → list        high
  POST    /pets                                 → create      high
  GET     /pets/{petId}                         → fetch       high
  POST    /pets/{petId}                         → update      high
  PATCH   /pets/{petId}                         → update      high
  DELETE  /pets/{petId}                         → delete      high
  DELETE  /pets/{petId}/avatar                  → delete      high
  GET     /pets/{petId}/vaccinations            → list        high
  POST    /pets/{petId}/verify                  → generic     high
  GET     /owners                               → list        high
  POST    /owners                               → create      high
  GET     /owners/{ownerId}                     → fetch       high
  GET     /store/inventory                      → fetch       high
  GET     /store/orders                         → list        high
  POST    /store/orders                         → create      high
  GET     /store/orders/{orderId}               → fetch       high
  PUT     /store/orders/{orderId}               → update      high
  DELETE  /store/orders/{orderId}               → delete      high
  GET     /clinics                              → list        high
  POST    /clinics                              → create      high
  GET     /clinics/{clinicId}                   → fetch       high
  PUT     /clinics/{clinicId}                   → update      high
  DELETE  /clinics/{clinicId}                   → delete      high
  GET     /clinics/{clinicId}/rooms             → list        high
  POST    /clinics/{clinicId}/rooms             → create      high
  GET     /clinics/{clinicId}/rooms/{roomId}    → fetch       high
  GET     /me                                   → fetch       high

Listening on :8080 (deterministic mode, strict=false)

curl http://localhost:8080/pets/42

{
  "id": "d1b2f3a4-5678-9abc-def0-1234567890ab",
  "name": "Fido",
  "status": "available",
  "age": 3,
  "tag": "domestic",
  "created_at": "2024-08-15T10:30:00Z"
}

The same request always returns the same response. Spec-authored examples ("Fido", "available") are used directly — the rest is generated from the schema.

What behavioral inference enables

Because Mimikos understands what each endpoint does, everything else follows:

• Correct status codes. Creates return 201. Deletes return 204. Fetches of missing resources return 404.
• Stateful mode just works. POST stores, GET retrieves, DELETE removes. No routing config.
• Error responses match the behavior. Validation errors for creates, not-found for fetches.
• No drift. Your spec changes, you restart, everything updates. No mock files to edit. No imports to re-run.

Your spec is the only config

Your OpenAPI spec is the only input. Mimikos validates every incoming request against it. Generates every response from it. Enforces every constraint in it.

example values you define in the spec are used directly — the data you authored is the data you get back. The rest is generated from schemas with realistic, field-aware values.

One file, one source of truth, zero configuration.

Install

Pre-built binary

Download from GitHub Releases for Linux, macOS, and Windows.

# macOS / Linux
tar -xzf mimikos_<os>_<arch>.tar.gz
sudo mv mimikos /usr/local/bin/
mimikos --version

macOS: if blocked on first run, see troubleshooting.

Go install

go install github.com/mimikos-io/mimikos/cmd/mimikos@latest

Requires Go 1.25+.

Works with your AI agent

Mimikos is an MCP server — Claude Code, Cursor, and VS Code Copilot can start, query, and manage mock servers through tool calls. Start a server, create test resources, and inspect responses — without leaving your editor.

claude mcp add mimikos -- mimikos mcp

Why Mimikos?

Your spec is enough

You already wrote the schemas, examples, and status codes. Why are you writing them again in mock configs? Mimikos uses what you already have. One file, zero duplication.

Stable snapshots

Your snapshot tests break every time a field changes. Mimikos uses per-field sub-seeding — add a field to the schema, existing values stay stable. Same request, same response, every time.

Realistic data

A field called email should return an email, not string_abc123. Mimikos maps 120+ field patterns to realistic generators — without annotations like x-faker.

Schema evolution safe

Update your spec, restart, done. No mock files to edit. No imports to re-run. Existing field values stay stable — only the new fields get new values.

Stateful CRUD

POST creates, GET retrieves, DELETE removes — automatically. Your mock server doesn’t need business logic, it needs to understand the API contract. --mode stateful and you’re done.

Useful errors

Send a malformed request, get a structured error telling you exactly which field failed and why. RFC 7807 Problem Details with field-level diagnostics — not a generic 500.

Coming from another mock tool?

Switching from Prism or similar? No x-faker annotations. Stateful CRUD mode. Deterministic output with per-field sub-seeding. Get started →

Single binary, zero dependencies

No runtime dependencies. No containers. No services to manage. One binary that reads your spec and serves responses.

mimikos start your-api.yaml
# That's it.

Get Started →