Mocktail
Free, 13MB, containerized, self-hosted mock server.
Installation
npx mocktailAsk AI about Mocktail
Powered by Claude Β· Grounded in docs
I know everything about Mocktail. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Mocktail
Mocktail is completely free, lightweight (~13MB), self-hosted, containerized mock server with a modern dashboard.
No limitations or restrictions. Mock any HTTP request. Export and import your mocks.
Quickstart π β’ Features β¨ β’ Changelog π β’ v3.0 Changes π₯
Note: Looking for v2? See v2.0.3 - the last stable v2 release.
Quickstart
Docker π³
Run Mocktail in a Docker container π³
docker run -p 4000:4000 -v $(pwd)/db:/db -d hhaluk/mocktail:3.1.6
The -v $(pwd)/db:/db flag mounts a local directory to persist your mock data.
Go to localhost:4000 π
Docker Compose π³
Run with Docker Compose
docker-compose up -d
Or build and run:
docker-compose up -d --build
Go to localhost:4000 π
The database is automatically persisted in ./mocktail-api/db/ on your host machine.
Features
- Create Mock APIs - Support for GET/POST/PUT/PATCH/DELETE methods
- Custom Status Codes - Return any HTTP status (200, 404, 500, etc.) to test error handling
- Response Delays - Add 0-30000ms delay to simulate network latency and loading states
- JSON Editor - CodeMirror-powered editor with syntax highlighting, error detection, and code folding
- Code Examples - Instantly generate cURL, Node.js, Python, and Go code snippets for any endpoint
- Randomize & Anonymize β οΈ Beta - Generate realistic fake data with 20+ faker types plus Custom (fixed value) and AI Generate (prompt-based) modes, with per-field configuration, live preview, and "apply same value to all" support
- Irregular Array Support - Handles arrays with inconsistent object structures, showing field frequency and applying configs selectively
- Modern Dashboard - Clean, intuitive interface built with React and Chakra UI v3
- Catalog View - Browse, search, and manage all your mock endpoints with quick actions and persistent selection
- Quick Edit - Update status codes and delays instantly via gear icon in catalog
- Test Endpoints - Test mocks directly from the catalog list with visual feedback
- Import/Export - Export mocks to JSON and import them anywhere
- Persistent Storage - SQLite database with volume mounting
- Multi-Platform - Native support for amd64 and arm64 (Intel, Apple Silicon, Raspberry Pi)
- Health Check -
/healthendpoint for monitoring and orchestration - Customizable URLs - Override display URLs for reverse proxy/custom domain setups
MCP Server (AI Integration)
Mocktail includes an MCP (Model Context Protocol) server that lets AI assistants like Claude manage your mock endpoints through natural language. Available on npm as mocktail-mcp.
Examples: "List all my mocks", "Create a GET /api/users mock returning a list of users", "Import mock endpoints for a blog API."
Available Tools
| Tool | Description |
|---|---|
list_mocks | List all configured mock endpoints |
create_mock | Create a single mock endpoint |
update_mock | Update an existing mock by ID |
delete_mock | Delete a mock by ID |
import_mocks | Bulk import multiple mocks (skips duplicates) |
Setup
npx (Recommended)
Claude Code
claude mcp add mocktail \
-e MOCKTAIL_URL=http://localhost:4000 \
-e MOCKTAIL_API_KEY=your-api-key \
-- npx mocktail-mcp
Claude Desktop
Add to your config file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{
"mcpServers": {
"mocktail": {
"command": "npx",
"args": ["mocktail-mcp"],
"env": {
"MOCKTAIL_URL": "http://localhost:4000",
"MOCKTAIL_API_KEY": "your-api-key"
}
}
}
}
From source (Development)
If you cloned the repo and want to run the MCP server locally:
Claude Code
claude mcp add mocktail \
-e MOCKTAIL_URL=http://localhost:4000 \
-e MOCKTAIL_API_KEY=your-api-key \
-- node /path/to/mocktail/mcp-server/index.js
Claude Desktop
{
"mcpServers": {
"mocktail": {
"command": "node",
"args": ["/path/to/mocktail/mcp-server/index.js"],
"env": {
"MOCKTAIL_URL": "http://localhost:4000",
"MOCKTAIL_API_KEY": "your-api-key"
}
}
}
}
Environment Variables:
| Variable | Required | Description |
|---|---|---|
MOCKTAIL_URL | Yes | Base URL of your Mocktail instance (e.g. http://localhost:4000) |
MOCKTAIL_API_KEY | No | API key sent as X-API-Key header on all requests |
Note: If you configured
MOCKTAIL_BASE_URLfor a custom domain or reverse proxy, use that same URL forMOCKTAIL_URL(e.g.https://api.mycompany.com/mocktailbecomesMOCKTAIL_URL=https://api.mycompany.com).
See
mcp-server/README.mdfor more details.
Configuration
Environment Variables
MOCKTAIL_BASE_URL (optional)
Override the Mocktail URL displayed in the dashboard. Useful when deploying behind a reverse proxy or custom domain.
Note: The legacy
REACT_APP_MOCKTAIL_URLenvironment variable is still supported for backwards compatibility.
# Example: Custom domain
MOCKTAIL_BASE_URL=https://api.mycompany.com/mocktail
# Example: Reverse proxy
MOCKTAIL_BASE_URL=https://gateway.example.com/mocktail
If not set, defaults to:
- Development:
http://localhost:4000/mocktail - Production:
[your-domain]/mocktail
CORS Configuration (optional)
Configure Cross-Origin Resource Sharing (CORS) policies for the mock API.
# Allowed origins (comma-separated)
# Default: * (allow all)
MOCKTAIL_CORS_ORIGINS=https://myapp.com,http://localhost:3000
# Allowed HTTP methods (comma-separated)
# Default: GET,POST,PUT,PATCH,DELETE,OPTIONS
MOCKTAIL_CORS_METHODS=GET,POST,PUT,DELETE
# Allowed headers (comma-separated)
# Default: * (allow all)
MOCKTAIL_CORS_HEADERS=Content-Type,Authorization,X-API-Key
# Allow credentials (cookies, auth headers)
# Default: false
MOCKTAIL_CORS_CREDENTIALS=true
Docker Example:
docker run -p 4000:4000 \
-e MOCKTAIL_CORS_ORIGINS=https://myapp.com \
-e MOCKTAIL_CORS_CREDENTIALS=true \
hhaluk/mocktail:latest
Docker Compose Example:
services:
mocktail:
image: hhaluk/mocktail:latest
ports:
- "4000:4000"
environment:
MOCKTAIL_CORS_ORIGINS: "https://myapp.com,http://localhost:3000"
MOCKTAIL_CORS_CREDENTIALS: "true"
volumes:
- ./db:/db
β οΈ Important Security Rule:
DO NOT combine wildcard origins with credentials:
# β INVALID - Browsers will reject this combination
MOCKTAIL_CORS_ORIGINS=*
MOCKTAIL_CORS_CREDENTIALS=true
# β
VALID - Use specific origins with credentials
MOCKTAIL_CORS_ORIGINS=https://myapp.com,http://localhost:3000
MOCKTAIL_CORS_CREDENTIALS=true
# β
VALID - Use wildcard without credentials (default)
MOCKTAIL_CORS_ORIGINS=*
MOCKTAIL_CORS_CREDENTIALS=false
When MOCKTAIL_CORS_CREDENTIALS=true, you must specify exact origins (no * wildcard).
MOCKTAIL_API_KEY (optional)
Protect mock endpoints with API key authentication. When set, all requests to /mocktail/* must include the API key.
# Set API key
MOCKTAIL_API_KEY=your-secret-key-here
Usage:
Clients must provide the key via header or query parameter:
# Via header (recommended)
curl http://localhost:4000/mocktail/users \
-H "X-API-Key: your-secret-key-here"
# Via query parameter
curl http://localhost:4000/mocktail/users?api_key=your-secret-key-here
What's Protected:
- π Mock endpoints (
/mocktail/*) - Requires API key - β
Dashboard (
/) - No auth needed - β
Core API (
/core/v1/*) - No auth needed (dashboard uses this) - β
Health check (
/health) - No auth needed
Security Note: If not set, mock endpoints are open (no authentication). This is fine for local development or private networks.
Recent Changes
See the full Changelog for all release notes.
v3.1.6 β Backend & MCP endpoint leading-slash normalization (fixes /mocktail//posts/1-style double-slash URLs)
v3.1.5 β MCP endpoint path normalization (fixes double slashes), catalog pagination
v3.1.4 β MCP Server AI integration (npx mocktail-mcp), Randomize & Anonymize UX overhaul (three-column layout, Custom & AI Generate types)
v3.1.3 β Backend Logs tab with real-time monitoring, enhanced code examples with API key support, critical Go string mutation bugfix
v3.1.2 β API key authentication, configurable CORS, .env file support
v3.1.1 β Cross-reference detection, review modal, Randomize & Anonymize improvements
v3.0 Changes
π What's New
- Custom Status Codes & Delays - Configure HTTP status codes and response delays per endpoint
- CodeMirror JSON Editor - Professional code editor with syntax highlighting and error detection
- Quick Actions - Test, edit, copy, and delete directly from the catalog list with icon buttons
- Chakra UI v3 - Complete UI library upgrade with modern components
- Go 1.24 & GORM v2 - Latest backend stack with improved performance
- Fiber v2.52 - Updated web framework with security patches
- Cleaner Architecture - Improved code organization and consistency
- Health Endpoint -
/healthfor Docker health checks and monitoring - Auto-Setup - Database directory auto-creates on first run
- Import/Export UI - Moved to Catalog tab with better UX
π What Changed
- Import Tab Removed - Import functionality now in Catalog tab
- Drag & Drop Removed - Simplified to native file input
- react-dropzone Removed - Reduced dependencies
β οΈ Breaking Changes
v3.0 is not backwards compatible with v2.x databases.
However, you can migrate your data:
- In v2, export your mocks to JSON (Catalog β Export)
- Install v3.0
- Import the JSON file (Catalog β Import)
Your mock endpoints will work unchanged - only the internal database structure changed.
Development
Local Development π
Using Makefile (Recommended)
# Run backend dev server
make dev-api
# Run dashboard dev server (in another terminal)
make dev-dashboard
# Build everything
make build
# Build Docker image
make build-docker
Manual Setup
Backend:
cd mocktail-api
go run main.go
Dashboard:
cd mocktail-dashboard
yarn install
yarn start
Backend runs on localhost:4000, Dashboard on localhost:3001
VSCode debug configuration is included for Go debugging.
