Install AgentBrush and Connect It to Claude or Cursor
By the end of this guide you will have AgentBrush running as an MCP server inside Claude Code, Cursor, or whichever MCP-compatible client you use. Your agent will be able to generate images, strip backgrounds, and save files directly into your project, without an OpenAI key, without a separate web app, and without leaving your editor. The whole setup takes about two minutes.
What you are installing
AgentBrush is an MCP server. It exposes image generation as a set of tools that any MCP-compatible agent can call. Your agent asks it for an image, AgentBrush calls gpt-image-2 on your behalf (under your AgentBrush subscription), and the result lands in your project folder. No API key wiring, no copy-pasting URLs, no tab-switching.
The server is distributed as an npm package: @agentbrush/mcp-server.
You have two options: run it on demand with `npx`, or install it globally.
**On-demand (recommended for a quick test):**
```bash
npx -y @agentbrush/mcp-server init
```
This downloads and runs the init flow without installing anything permanently. Good for confirming it works before committing.
**Global install (recommended for everyday use):**
```bash
npm install -g @agentbrush/mcp-server
```
After a global install, the `agentbrush-mcp` binary is on your PATH and every client config below will work exactly as shown.
Run the init command once to log in:
```bash
agentbrush-mcp init
```
This opens a browser tab with a device-code login flow. Sign in with your AgentBrush account (or create one, it is free), approve the device, and close the tab. That is it. Your credentials are saved locally and the server picks them up automatically on every subsequent run. You will not be prompted again unless you explicitly log out or move to a new machine.
**Where credentials are stored:**
- macOS and Linux: `~/.agentbrush/credentials.json`
- Windows: `%USERPROFILE%\.agentbrush\credentials.json`
The file stays on your machine. AgentBrush does not persist it anywhere else.
How you register the server depends on which client you use.
### Claude Code
```bash
claude mcp add agentbrush --scope user -- agentbrush-mcp
```
The `--scope user` flag installs the server for every Claude Code session on this machine, not just the current project. You run this once and it applies everywhere.
### Cursor, Gemini CLI, and other MCP-compatible clients
Add the following to your client's MCP config JSON (usually `mcp.json` or the equivalent settings file):
```json
{
"mcpServers": {
"agentbrush": {
"command": "agentbrush-mcp"
}
}
}
```
For **Codex CLI**, the root key is `"servers"` instead of `"mcpServers"`:
```json
{
"servers": {
"agentbrush": {
"command": "agentbrush-mcp"
}
}
}
```
After saving the config, restart your client so it picks up the new server.
### Supported clients
AgentBrush works with Claude Code, Cursor, Codex CLI, Gemini CLI, and any MCP-compatible client. If your client supports the Model Context Protocol, the JSON config above is all it needs.
Once the server is registered, ask your agent for something simple:
```text
Generate a flat illustration of a coffee cup on a wooden desk, warm morning light.
preset: flat_illustration ยท quality: medium
```
The image saves into your project folder. If it does, the setup is working. Medium quality uses 5 tokens and is the right choice for testing: fast, cheap, and good enough to confirm the pipeline end-to-end. Switch to `quality: high` (20 tokens) when you are ready to produce a real asset.
Troubleshooting
The agentbrush-mcp command is not found. The global install may not have landed on your PATH. Run npm install -g @agentbrush/mcp-server again and confirm the output directory is in your PATH, or use the npx -y @agentbrush/mcp-server form everywhere instead.
The client does not see the server after adding the config. Restart the client fully. Most MCP clients read their config at startup, not live. Verify the JSON is valid (a trailing comma or missing bracket is enough to silently break it).
The init command opens a browser but login fails. Check that your browser is not blocking the redirect back to localhost. If you are on a remote machine or a headless environment, copy the device code from the terminal and enter it manually at the URL the command prints.
The agent reports the server is unreachable. Open a fresh terminal and run agentbrush-mcp to confirm it starts without errors. If it prints a credentials error, run agentbrush-mcp init again. The server will re-run the auth flow and refresh the stored token.
FAQ
Do I need my own OpenAI API key? No. Your agent calls AgentBrush, and AgentBrush calls gpt-image-2 under your AgentBrush subscription. You do not touch the OpenAI API directly and you do not need an OpenAI account.
Is it free to start? Creating an account is free, but generating images needs a paid plan. There is no free token tier. Starter is $6.99 per month for 100 tokens, Pro is $14.99 for 600, and Power is $29.99 for 1,300, with overage at $0.04 per token on Power.
Which clients work?
Claude Code, Cursor, Codex CLI, Gemini CLI, and any other MCP-compatible client. If the client supports the Model Context Protocol and accepts a command-style server config, AgentBrush will work with it.
What can I do after the first image?
The same agent session handles background removal (Remove the background from that image), reference-based generation for consistency, and the mask editor for region-level edits. The prompting guide covers the full surface area once you are set up.
Where do generated images land? By default, in the working directory your agent has open at the time of the request. You can specify an output path in your prompt, and AgentBrush will use it.
Ready to try it? Connect AgentBrush to your agent and run a prompt. The first image lands in your project in under a minute.
For what to generate once you are set up, see the best ways to generate images inside Claude and Cursor. For a deeper look at what the underlying model can do, see what gpt-image-2 means for image generation inside your AI agent.