Skip to main content

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 CloudSelf-Hosted (OSS)
SetupAPI key + URL onlyBuild step required
Authx-api-key headerEnvironment variable
Server URLhttps://app.maxun.dev/api/mcpYour 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
Generate API Key
API Key Generated
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.

MCP Server Initialized

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:

VariableDescription
MAXUN_LLM_PROVIDERanthropic, openai or ollama
MAXUN_LLM_MODELModel name, e.g. claude-sonnet-4-5, gpt-4o or llama3.1
MAXUN_LLM_API_KEYAPI key for Anthropic or OpenAI
MAXUN_LLM_BASE_URLBase 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.

Upgrading

After updating your Maxun project, run npm run mcp:build again and restart your client to get the latest tools.