MCP Server Setup
Maxun MCP Server lets you connect any MCP-compatible AI client (Claude Desktop, Cursor, Windsurf, Cline, Claude Code, etc.) to Maxun. Your AI client can then:
- Scrape any page into clean markdown, HTML, text, links or screenshots, and answer questions about it
- Crawl whole websites
- Search the web and scrape the results
- Extract structured data by describing it in plain language, with an AI agent
- Run and monitor the robots you already have, including Recorder Mode robots
See MCP Tools for every tool and its options.
There are two variants depending on how you use Maxun:
| Maxun Cloud | Self-Hosted (OSS) | |
|---|---|---|
| Setup | API key + URL only | Build step required |
| Auth | x-api-key header | Environment variable |
| Server URL | https://app.maxun.dev/api/mcp | Your local backend |
Maxun Cloud
No build step needed. Connect directly to the cloud API with your Maxun API key.
Prerequisites
- A Maxun Cloud account at app.maxun.dev
- An MCP-compatible client (Claude Desktop, Cursor, Windsurf, Cline, etc.)
1. Generate your API Key
Go to your Maxun Dashboard and navigate to Settings → API Key to generate a key.
![]() |
|---|
| Generate API Key |
![]() |
|---|
| API Key Generated |
2. Configure your MCP client
Choose the configuration format that matches your client.
Native HTTP
{
"mcpServers": {
"maxun": {
"url": "https://app.maxun.dev/api/mcp",
"headers": {
"x-api-key": "your_api_key_here"
}
}
}
}
Via mcp-remote (stdio bridge)
If your client does not support the url + headers format natively, use mcp-remote as a stdio-to-HTTP bridge — no separate install needed, npx handles it automatically.
{
"mcpServers": {
"maxun": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://app.maxun.dev/api/mcp",
"--header",
"x-api-key:your_api_key_here"
]
}
}
}
Most clients store this config as a JSON file. For example, in Claude Desktop it is at:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
Check your client's documentation for the exact config file location.
3. Restart your client
After saving the config, restart the application. On success you will see the Maxun tools available in the client.

Use a team's robots
By default the MCP server works with your personal robots. To work with a team's robots instead, add an x-team-id header with the team ID (shown on the Teams page of the dashboard). Your team role applies: viewers can list and read robots and runs, members can also create and run them.
{
"mcpServers": {
"maxun": {
"url": "https://app.maxun.dev/api/mcp",
"headers": {
"x-api-key": "your_api_key_here",
"x-team-id": "your_team_id_here"
}
}
}
}
With mcp-remote, add another "--header", "x-team-id:your_team_id_here" pair to args.
Claude Code
Add the server from your terminal:
claude mcp add --transport http maxun https://app.maxun.dev/api/mcp --header "x-api-key: your_api_key_here"
Self-Hosted (OSS)
Use this if you are running the open-source Maxun instance locally or on your own server.
Prerequisites
- Maxun OSS running locally (default:
http://localhost:8080) - Node.js installed
1. Build the MCP worker
Run the following command from the root of your Maxun project:
npm run mcp:build
This generates dist/mcp-worker.js in your project root.
2. Generate your API Key
Generate the API Key from your self-hosted Maxun Dashboard under Settings → API Key.
3. Configure your MCP client
Add the following to your client's MCP server config. For example, in Claude Desktop go to File → Settings → Developer → Edit Config:
{
"mcpServers": {
"maxun": {
"command": "node",
"args": [
"/path/to/your/project/dist/mcp-worker.js"
],
"env": {
"MCP_API_KEY": "your_api_key_here",
"BACKEND_URL": "your_backend_url_here",
"MCP_WORKER": "true"
}
}
}
}
Replace /path/to/your/project with the absolute path to your Maxun project directory, and your_backend_url_here with your backend URL (e.g. http://localhost:8080).
After saving, restart your client. You'll see the Maxun tools available on successful configuration.
4. (Optional) Configure an LLM
Self-hosted Maxun uses your own LLM for AI features. To use maxun_agent, the summary output format or smart queries in maxun_scrape, add these to the env block above:
| Variable | Description |
|---|---|
MAXUN_LLM_PROVIDER | anthropic, openai or ollama |
MAXUN_LLM_MODEL | Model name, e.g. claude-sonnet-4-5, gpt-4o or llama3.1 |
MAXUN_LLM_API_KEY | API key for Anthropic or OpenAI |
MAXUN_LLM_BASE_URL | Base URL for Ollama, e.g. http://localhost:11434 |
"env": {
"MCP_API_KEY": "your_api_key_here",
"BACKEND_URL": "http://localhost:8080",
"MCP_WORKER": "true",
"MAXUN_LLM_PROVIDER": "anthropic",
"MAXUN_LLM_MODEL": "claude-sonnet-4-5",
"MAXUN_LLM_API_KEY": "your_anthropic_key_here"
}
The key is sent to your own Maxun backend only. Everything else, including scrape, crawl and search, works without an LLM.
After updating your Maxun project, run npm run mcp:build again and restart your client to get the latest tools.

