Mockzilla HTTP Server Documentation

Getting Started

Quick Start with Docker

Mockzilla is designed for easy self-hosting with Docker. Choose between fast in-memory storage or persistent PostgreSQL based on your needs.

🚀 Option 1: Fast Start (In-Memory)

Perfect for development and testing. Data is stored in memory by default.

// Pull the latest image

                    docker pull andrecrjr/mockzilla:latest

                    // Start Mockzilla

                    docker run -p 36666:36666 andrecrjr/mockzilla:latest

Access your mock server at http://localhost:36666

💾 Option 2: With Volume Persistence

Keep your mocks between container restarts while using fast in-memory database.

                    docker run -d --name mockzilla -p 36666:36666 -v mockzilla-data:/data andrecrjr/mockzilla:latest
                

🗄️ Option 3: With PostgreSQL (Production)

For production environments with external PostgreSQL database.

                    docker run -d --name mockzilla -p 36666:36666 -e
                    DATABASE_URL=postgresql://user:pass@host:5432/mockzilla andrecrjr/mockzilla:latest
                

📍 Next Steps

• Visit http://localhost:36666 to access the UI
• Create your first mock folder
• Add mocks with dynamic responses using JSON Schema

Deployment Options

Running in Background

For long-running deployments, use the -d flag to run in detached mode:

                    docker run -d --name mockzilla -p 36666:36666 -v mockzilla-data:/data andrecrjr/mockzilla:latest
                

Container Management

View logs:

docker logs mockzilla

Stop container:

docker stop mockzilla

Restart container:

docker restart mockzilla

Remove container:

docker rm -f mockzilla

Environment Variables

DATABASE_URL

PostgreSQL connection string (optional)

postgresql://user:pass@host:5432/database

PORT

Server port (default: 36666)

Using Mockzilla

Creating Mocks

1. Create a Folder

Organize your mocks by creating folders for different projects or features.

2. Add a Mock Endpoint

Define your API endpoint (e.g., /api/users) with HTTP method and status code.

3. Choose Response Type

Static JSON: Fixed response for simple cases
Dynamic Schema: Generate realistic data with JSON Schema + Faker

4. Test Your Mock

Use the built-in preview or make requests to http://localhost:36666/mock/[your-endpoint]

💡 Pro Tip

Use JSON Schema with Faker for realistic mock data. For example, use faker.person.fullName for names or faker.internet.email for emails.

Stateful Workflows

Create complex multi-step flows with persistent state. Perfect for simulating:

Login/logout flows with session tracking
Shopping carts with add/remove operations
Multi-step form submissions
API requests that depend on previous calls

Use Workflow Scenarios in the UI to create transitions with conditions and effects.

AI/MCP Integration

Model Context Protocol (MCP)

Let AI agents create and manage your mocks. Mockzilla exposes 24 specialized tools via MCP for complete automation. Connect your private server to modern AI agents like Claude Desktop or Cursor.

Connection Options

Option 1: Direct URL (Recommended)

Modern MCP clients (Cursor, custom agents) can connect directly:

http://localhost:36666/api/mcp

Option 2: Claude Desktop Settings

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "mockzilla": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:36666/api/mcp"]
    }
  }
}

24 Available Tools

📁 Folders (5 tools)

• List, create, get, update, delete

🎯 Mocks (7 tools)

• List, create, get, update, delete, preview

🔄 Scenarios (5 tools)

• Manage workflow scenarios

⚡ State (7 tools)

• Inspect and control workflow state

💡 Pro Tips

• Use create_schema_mock for realistic data mocks
• Use inspect_workflow_state when debugging workflows
• Install Agent Skills for specialized patterns

Agent Skills (Optional)

Install expert patterns for your AI agent to build complex mocks and architectures:

npx add-skill https://github.com/andrecrjr/mockzilla

Chrome Extension Sync

Server-Extension Synchronization

Sync your Chrome Extension mocks to the Mockzilla server to share with your team and back up your work.

Mockzilla Server must be in version >= 1.0.0

Quick Steps

0.

Install the extension from the Chrome Web Store

1.

After that can follow the #getting-started section to install the server

2.

Open extension rule manager then enable "Mockzilla Server Sync" for your rules

3.

Each rule has your own sync button

4.

Set server URL: http://localhost:36666 or use your VPS server URL

5.

Click "Sync Now" - mocks appear on server in "Extension" section

6.

Click "AUTO" - extension will sync that rule to server automatically (every rule update in extension)

💡 High-Fidelity Storage

Extension-specific features (like variants) are preserved on the server even if not displayed in the UI. When you import back to the extension, all features are restored.

Self-Host Your Own Mockzilla Server

Easy Docker Deploy

Flexible Storage

Team Collaboration