# AgentQL

> Query webpages with structured natural language — selectors written for you.

[Canonical HTML page](https://top-mcps.com/mcp/agentql) · [server.json](https://top-mcps.com/mcp/agentql.json) · [methodology](https://top-mcps.com/about/methodology)

## Install

### Claude Desktop — `claude_desktop_config.json`

Paste under mcpServers. Fully quit and reopen Claude after editing.

```json
{
  "mcpServers": {
    "agentql": {
      "command": "npx",
      "args": [
        "-y",
        "agentql-mcp"
      ],
      "env": {
        "AGENTQL_API_KEY": "${AGENTQL_API_KEY}"
      }
    }
  }
}
```

### Claude Code — `CLI or .mcp.json`

Run from your repo. Commit .mcp.json to share with your team.

```shell
# export AGENTQL_API_KEY=YOUR_API_KEY
claude mcp add agentql -- npx -y agentql-mcp
```

### Cursor — `.cursor/mcp.json`

Global path: ~/.cursor/mcp.json. Reload window after editing.

```json
{
  "mcpServers": {
    "agentql": {
      "command": "npx",
      "args": [
        "-y",
        "agentql-mcp"
      ],
      "env": {
        "AGENTQL_API_KEY": "${AGENTQL_API_KEY}"
      }
    }
  }
}
```

### VS Code — `.vscode/mcp.json`

VS Code uses the "servers" key (not "mcpServers").

```jsonc
{
  "servers": {
    "agentql": {
      "command": "npx",
      "args": [
        "-y",
        "agentql-mcp"
      ],
      "env": {
        "AGENTQL_API_KEY": "${AGENTQL_API_KEY}"
      }
    }
  }
}
```

### Windsurf — `~/.codeium/windsurf/mcp_config.json`

Open via Cascade → hammer icon → Configure.

```json
{
  "mcpServers": {
    "agentql": {
      "command": "npx",
      "args": [
        "-y",
        "agentql-mcp"
      ],
      "env": {
        "AGENTQL_API_KEY": "${AGENTQL_API_KEY}"
      }
    }
  }
}
```

### Cline — `cline_mcp_settings.json`

Open via the Cline sidebar → MCP Servers → Edit.

```json
{
  "mcpServers": {
    "agentql": {
      "command": "npx",
      "args": [
        "-y",
        "agentql-mcp"
      ],
      "env": {
        "AGENTQL_API_KEY": "${AGENTQL_API_KEY}"
      }
    }
  }
}
```

### Continue — `~/.continue/config.json`

Continue uses modelContextProtocolServers with a transport block.

```json
{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "npx",
          "args": [
            "-y",
            "agentql-mcp"
          ],
          "env": {
            "AGENTQL_API_KEY": "${AGENTQL_API_KEY}"
          }
        }
      }
    ]
  }
}
```

### Codex CLI — `~/.codex/config.toml`

Codex uses TOML. Each server is a [mcp_servers.<name>] subtable.

```shell
# ~/.codex/config.toml
[mcp_servers.agentql]
command = "npx"
args = [
  "-y",
  "agentql-mcp",
]
env = { AGENTQL_API_KEY = "${AGENTQL_API_KEY}" }
```

### Zed — `~/.config/zed/settings.json`

Zed calls them "context_servers". Settings live-reload on save.

```jsonc
{
  "context_servers": {
    "agentql": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "agentql-mcp"
        ]
      },
      "env": {
        "AGENTQL_API_KEY": "${AGENTQL_API_KEY}"
      }
    }
  }
}
```

### ChatGPT — `ChatGPT → Apps directory`

AgentQL doesn't ship a hosted HTTPS endpoint today. ChatGPT supports remote MCP servers only — to use this server in ChatGPT you'll need to deploy it to a public HTTPS URL first (e.g. via Cloudflare Workers or Vercel) or wait for an official remote build.

```none

```

## At a glance

- **Maintainer:** Tinyfish
- **Transport:** stdio
- **Auth model:** API key
- **Required secrets:** AGENTQL_API_KEY
- **Supported clients:** Claude, Cursor, Any MCP-compatible client
- **License:** MIT
- **Language:** TypeScript
- **Latest version:** latest
- **Last verified:** 2026-05-26
- **GitHub stars:** 171 (fetched 2026-05-26T10:50:22.921Z)
- **Score:** 74/100 (rubric 2026-04 — see https://top-mcps.com/about/methodology)
- **Source:** https://github.com/tinyfish-io/agentql-mcp

## Security & scope

- **Access scope:** network
- **Sandbox:** Queries are executed on AgentQL's hosted browser. Your API key is the only credential needed.
- **Gotchas:**
  - Pages are fetched by AgentQL's IP pool — sites that allowlist may need the IP added.
  - Queries that loop on pagination can accumulate cost quickly.

## Quick answer

**What it does.** Exposes AgentQL's query-and-extract surface: submit a URL plus a structured natural-language query, get back JSON matching the requested shape.

**Best for:**
- Structured page extraction
- Schema-driven scraping
- Bulk data collection from messy HTML
- JSON-first agent pipelines

**Not for:**
- Interactive multi-step flows
- Login-walled content
- Latency-sensitive single-call work

## Description

AgentQL is a query language for the web. Instead of writing CSS selectors, you describe the data you want ("find the price, title, and rating") and AgentQL returns structured JSON. The MCP wrapper lets an agent run AgentQL queries against any URL.

## Why it matters

Most extraction MCPs return Markdown and rely on the LLM to parse fields. AgentQL returns structured JSON typed to your schema — fewer hallucinated fields and easier downstream code.

## Key features

- Natural-language queries
- JSON output typed to your shape
- Resilient to layout changes
- Built-in pagination support

## FAQ

### How is it different from Firecrawl?

Firecrawl gives you cleaned Markdown of an entire page; AgentQL gives you a specific shape (price, title, rating) extracted from any layout. Use Firecrawl for "summarize this page," AgentQL for "pull these fields."

### Does it handle JavaScript-rendered pages?

Yes — AgentQL runs a real browser under the hood, so SPAs and dashboards work.

### What is the rate-limit posture?

Free tier allows a few hundred queries per month; paid plans scale linearly. Agents that loop will burn the free tier in minutes — set a daily budget.

## Changelog

- **2026-05-26** — Refreshed install snippets and fact sheet; verified for 2026.
- **2025-03-01** — Initial directory listing.