AIMock
Mock everything your AI app talks to — LLM APIs, MCP, A2A, AG-UI, vector DBs, search. One package, one port, zero dependencies.
What is AIMock?
AIMock is a Model Context Protocol (MCP) server that allows AI assistants like Claude, Cursor, and VS Code to mock everything your ai app talks to — llm apis, mcp, a2a, ag-ui, vector dbs, search. one package, one port, zero dependencies.
Mock everything your AI app talks to — LLM APIs, MCP, A2A, AG-UI, vector DBs, search. One package, one port, zero dependencies.
This server falls under the Developer Tools category on MCPgee, the world's largest MCP server directory with 33,000+ servers.
Features
- Mock everything your AI app talks to — LLM APIs, MCP, A2A, A
Use Cases
Maintainer
Works with
Installation
NPM
npx -y @copilotkit/aimockManual Installation
npx -y @copilotkit/aimockConfiguration
Configuration Details
claude_desktop_config.json
Performance
Response Metrics
Resource Usage
How to Set Up and Use AIMock
AIMock is a zero-dependency local mock server that intercepts and simulates every AI service your application calls, including OpenAI Chat and Responses APIs, Anthropic Claude, Google Gemini, vector databases (Pinecone, Qdrant, ChromaDB), MCP tools, and agent-to-agent protocols. It runs on a single port and ships as a single npm package, letting teams write deterministic AI integration tests without real API credentials or costs. Developers use it to speed up CI pipelines and reproduce edge-case LLM responses reliably.
Prerequisites
- Node.js 18 or higher installed
- npm, npx, or yarn available on your PATH
- An MCP client (Claude Desktop, Claude Code, or Cursor) for MCP server mode
- No real AI API keys required for local testing
Install the package
Install AIMock globally or use npx to run it without a permanent install. The package name on npm is @copilotkit/aimock.
npm install @copilotkit/aimock
# or run directly without installing:
npx -y @copilotkit/aimockStart the mock server via CLI
Launch the server with an optional config file. The server listens on a local port and exposes OpenAI-compatible endpoints by default.
npx @copilotkit/aimock --config aimock.jsonPoint your SDK clients at the mock
Set the OPENAI_BASE_URL environment variable to the local mock server before constructing any SDK clients. The API key value can be any non-empty string when mocking.
export OPENAI_BASE_URL=http://localhost:4010/v1
export OPENAI_API_KEY=mockUse AIMock programmatically in tests
Import LLMock (or MCPMock, VectorMock, etc.) in your test suite, define fixture responses, and start the server before your test runs.
import { LLMock } from "@copilotkit/aimock";
const mock = new LLMock({ port: 0 });
mock.onMessage("hello", { content: "Hi there!" });
await mock.start();
process.env.OPENAI_BASE_URL = `${mock.url}/v1`;
process.env.OPENAI_API_KEY = "mock";
// ... run your tests ...
await mock.stop();(Optional) Record real responses for replay
Use record mode to proxy real provider calls and save them as fixtures for later deterministic replay.
npx -p @copilotkit/aimock llmock --record --provider-openai https://api.openai.comConfigure as an MCP server
To use AIMock as an MCP server so Claude or Cursor can interact with mock AI services, add it to your MCP client configuration.
{
"mcpServers": {
"aimock": {
"command": "npx",
"args": ["-y", "@copilotkit/aimock"]
}
}
}AIMock Examples
Client configuration
Add AIMock as an MCP server in your Claude Desktop or Claude Code configuration file.
{
"mcpServers": {
"aimock": {
"command": "npx",
"args": ["-y", "@copilotkit/aimock"]
}
}
}Prompts to try
Use these prompts when AIMock is running as your local AI service mock during development and testing.
- "Start a mock OpenAI chat session and return a fixed greeting response"
- "Mock a Pinecone vector search returning the top 3 hardcoded results"
- "Simulate a Claude Anthropic streaming response for my integration test"
- "Set up a mock MCP tool that returns a fixed JSON payload when called"Troubleshooting AIMock
SDK clients still call the real API instead of the mock
Ensure OPENAI_BASE_URL is set BEFORE the SDK client object is constructed in your code. Environment variable changes after client instantiation are not picked up by most SDKs.
Fixture URLs pointing to local addresses are blocked
Set the environment variable AIMOCK_ALLOW_PRIVATE_URLS=1 before starting the server. This lifts the default restriction on local and private IP address ranges in fixture responses.
Record mode fails with authentication errors
Record mode proxies real provider calls, so you need a valid API key for the target provider during recording. Set the real key (e.g. OPENAI_API_KEY) in your environment before running with --record.
Frequently Asked Questions about AIMock
What is AIMock?
AIMock is a Model Context Protocol (MCP) server that mock everything your ai app talks to — llm apis, mcp, a2a, ag-ui, vector dbs, search. one package, one port, zero dependencies. It connects AI assistants to external tools and data sources through a standardized interface.
How do I install AIMock?
Install via npm with the command: npx -y @copilotkit/aimock. Then add the server configuration to your AI client's JSON config file (e.g., claude_desktop_config.json or .cursor/mcp.json).
Which AI clients work with AIMock?
AIMock works with all major MCP-compatible AI clients including Claude Desktop, Claude Code, Cursor, VS Code (GitHub Copilot), Windsurf, and Cline.
Is AIMock free to use?
Yes, AIMock is open source and available under the MIT license. You can use it freely in both personal and commercial projects.
AIMock Alternatives — Similar Developer Tools Servers
Looking for alternatives to AIMock? Here are other popular developer tools servers you can use with Claude, Cursor, and VS Code.
Ecc
★ 188.2kThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
Javaguide
★ 155.8kJava 面试 & 后端通用面试指南，覆盖计算机基础、数据库、分布式、高并发、系统设计与 AI 应用开发
Gemini CLI
★ 104.5kA secure MCP server that wraps the Google Gemini CLI, allowing clients to query Gemini models using local OAuth sessions without requiring an API key. It provides tools for model interaction and diagnostics with built-in protection against command in
Awesome MCP Servers
★ 87.3k⭐ Curated list of Model Context Protocol (MCP) servers - tools that extend Claude Desktop, Cursor, Windsurf, and other MCP clients with custom capabilities.
MCP Servers
★ 86.0kModel Context Protocol Servers
CC Switch
★ 77.5kA cross-platform desktop All-in-One assistant for Claude Code, Codex, OpenCode, OpenClaw, Gemini CLI & Hermes Agent. Only official website: ccswitch.io
Browse More Developer Tools MCP Servers
Explore all developer tools servers available in the MCPgee directory. Each server includes setup guides for Claude, Cursor, and VS Code.
Set Up AIMock in Your Editor
Choose your AI client for step-by-step setup instructions.
Quick Config Preview
Add this to your claude_desktop_config.json or .cursor/mcp.json
Ready to use AIMock?
Browse our complete directory of 33,000+ MCP servers, read setup guides for your editor, and start building with the Model Context Protocol.