Skip to content
automdevPublic

Repository files navigation

Autom MCP Server

Official Model Context Protocol server for the Autom SERP API.

Google, Bing and Brave search results as structured JSON — web, maps, news, shopping, images, jobs and AI Mode.

It lets Claude, Cursor, VS Code, Windsurf and any MCP client call the API as tools. Runs over stdio (local) or Streamable HTTP (self-hosted).

Requirements

  • Node.js 20 or newer
  • a Autom API key — sign up, then copy it from the dashboard

Hosted server (recommended)

Autom runs this server for you at https://mcp.autom.dev/ (Streamable HTTP). Send your API key in the x-api-key header; nothing to install.

claude mcp add --transport http autom https://mcp.autom.dev/ --header "x-api-key: YOUR_API_KEY"
{
  "mcpServers": {
    "autom": {
      "url": "https://mcp.autom.dev/",
      "headers": {
        "x-api-key": "YOUR_API_KEY"
      }
    }
  }
}

The hosted server and this package expose the same API; run the package locally when you want stdio, your own network egress, or to self-host it.

Run it locally

Claude Code

claude mcp add autom --env AUTOM_API_KEY=YOUR_API_KEY -- npx -y @automdev/mcp

Claude Desktop, Cursor, Windsurf and other clients

Add the server to the client's MCP configuration (claude_desktop_config.json, .cursor/mcp.json…):

{
  "mcpServers": {
    "autom": {
      "command": "npx",
      "args": ["-y", "@automdev/mcp"],
      "env": {
        "AUTOM_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

VS Code

{
  "servers": {
    "autom": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@automdev/mcp"],
      "env": {
        "AUTOM_API_KEY": "${input:autom-api-key}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "autom-api-key",
      "description": "Autom API key",
      "password": true
    }
  ]
}

Claude Desktop extension

Download the .mcpb bundle from the releases page and open it; Claude Desktop asks for your API key.

Docker

docker build -t autom-mcp .
docker run -i --rm -e AUTOM_API_KEY=YOUR_API_KEY autom-mcp

Tools

Tool Description
bing_search Query Bing Search via API and retrieve structured organic results (title, link, snippet, position).
brave_images Search Brave Images via API and retrieve structured image results with pagination and SafeSearch.
brave_search Search Brave Search via API and retrieve structured organic results with pagination.
brave_videos Search Brave Videos via API and retrieve structured video results with pagination and SafeSearch.
duckduckgo_search Query DuckDuckGo via API and retrieve structured organic results with region and language.
finder_google_countries Search Google countries and retrieve country codes (free Finder endpoint).
finder_google_languages Search Google languages and retrieve language codes (free Finder endpoint).
finder_google_locations Find supported Google locations and retrieve location IDs and country codes (free endpoint).
google_images Search Google Images via API and retrieve image results (URLs, titles, sources, dimensions).
google_jobs Scrape Google Jobs results via API and retrieve structured job listings with title, company, location, and pagination.
google_maps Search Google Maps via API and retrieve structured place results (address, website, phone).
google_news Search Google News via API and retrieve structured news results with pagination.
google_search Scrape Google Search results via API and retrieve structured SERP data with pagination.
google_search_ai Query Google AI Mode via API. JSON with text_blocks, references, and shopping_results.
google_search_autocomplete Get Google Search autocomplete suggestions via API for a given query.
google_search_light Scrape lightweight Google Search results via API: fast, cost-efficient, organic results only.
google_shopping Scrape Google Shopping results via API and retrieve structured product listings with prices, ratings, and merchant data.
google_videos Search Google Videos via API and retrieve structured video results with metadata.
search One call walks engines in order and returns the first organic results. engines=auto tries Google, then Brave, Bing, DuckDuckGo, Yahoo, and Baidu. Omitted gl is us and omitted hl is en. There is no pa…
stats Infrastructure health for an engine or endpoint over the last hour. Not scoped to your account or tenant. Enabled per account: HTTP 403 means contact support to activate it.
usage Retrieve real-time usage statistics and credit balance for your Autom account.
yahoo_search Query Yahoo via API and retrieve structured organic results with country and language.

Every tool that calls the API consumes credits. JSON results are returned as text; images are returned inline and other files (PDF…) as embedded resources, up to 4 MB.

Streamable HTTP

npx @automdev/mcp --http --port 3000

The endpoint is POST /mcp (stateless, JSON responses). Each client sends its own key in the x-api-key header (or Authorization: Bearer <key>); the server never uses a key of its own. It binds to 127.0.0.1 by default and rejects browser origins unless you allow them — put it behind TLS before exposing it.

createHttpHandler() is exported for Fetch-compatible runtimes (Cloudflare Workers, Deno, Bun):

import { createHttpHandler } from "@automdev/mcp";

export default { fetch: createHttpHandler({ allowedOrigins: [] }) };

Security

  • The API key is read from AUTOM_API_KEY (stdio) or the request headers (HTTP) and removed from error messages.
  • Content fetched from websites is untrusted: the server instructions tell the model to treat it as data, not instructions.
  • See SECURITY.md to report a vulnerability.

Development

npm install
npm test
npm run build
npx @modelcontextprotocol/inspector node dist/stdio.js

Built on the SDK

The server uses the official Node.js SDK (@automdev/sdk).

All Autom SDKs

SDK Package Install
Node.js @automdev/sdk npm install @automdev/sdk
Python automdev pip install automdev
Go autom-go go get github.com/automdev/autom-go
.NET Autom dotnet add package Autom
Ruby autom gem install autom
PHP autom/sdk composer require autom/sdk
Java autom-java build from source, see its README
CLI @automdev/cli npm install -g @automdev/cli
MCP server @automdev/mcp npx -y @automdev/mcp

License

MIT — see LICENSE.

Releases

Packages

Contributors

Languages