Agentql MCP

What tinyfish-io/agentql-mcp does

The tinyfish-io/agentql-mcp MCP server connects an MCP client to AgentQL's web data extraction capability. It provides one tool, extract-web-data, for requesting structured information from a specified web page.

A tool call includes a url and a prompt. The URL identifies the page to inspect, while the prompt describes the data to extract and the fields each result should contain. For example, an agent can ask for video titles, authors, view counts, and links from a search results page, while excluding advertisement items.

This fits workflows where an agent needs page-level data in a structured form rather than only a text summary. The repository does not document additional tools for navigation, browser control, writing data to another system, or general-purpose web search.

How it works

The server communicates with MCP clients over standard input and output. An MCP-compatible application starts the local agentql-mcp process, and the process exposes extract-web-data to the agent. The server uses the configured AgentQL credential when handling extraction requests.

The extraction request is expressed in natural language through the prompt. Developers can state which records to return, which fields to include, and which items to leave out. The README recommends explicitly telling the agent to use the AgentQL tool if it attempts to open URLs or load web content without invoking the server.

The tinyfish-io/agentql-mcp repository documents configuration examples for Claude Desktop, VS Code, Cursor, and Windsurf. Only Claude Desktop, Cursor, and Windsurf are listed as compatible clients in this directory's client taxonomy.

Setup and configuration

Install the npm package globally with npm install -g agentql-mcp, or configure an MCP client to start it with npx -y agentql-mcp. An AgentQL API key is required and can be obtained from the AgentQL developer portal.

Set the key in the AGENTQL_API_KEY environment variable. Claude Desktop, VS Code, and Windsurf examples place that variable in the server configuration. Cursor's documented command also supplies the variable before starting the package. Keep the value out of shared configuration files where possible; the README's VS Code setup supports a password-style input for the key.

For a typical stdio configuration, the relevant shape is:

{
  "command": "npx",
  "args": ["-y", "agentql-mcp"],
  "env": {
    "AGENTQL_API_KEY": "your-key"
  }
}

The development workflow uses npm install, npm run build, and npm run watch. The repository also documents npm run inspector for launching the MCP Inspector during debugging.

Tools and capabilities

• extract-web-data: extracts structured data from a URL according to a natural-language field description.
• Accepts prompts that define the expected data fields.
• Can be used for lists of records, such as search results, when the requested page exposes those records.
• Supports MCP clients configured to launch the server through npm and stdio.

Limitations and notes

The documented interface contains one extraction tool; there is no material here supporting separate tools for clicking, form submission, crawling multiple pages, or exporting results. Extraction depends on a valid AGENTQL_API_KEY, and the README does not specify API quotas, pricing, supported sites, response schemas, or guarantees about pages that require authentication.

The tinyfish-io/agentql-mcp server is intended to be selected explicitly by the agent for web extraction. If a client instead reports that it cannot access a URL, the README suggests adding a direction such as “use tools” or “use agentql tool.”

Getting started with this tinyfish-io/agentql-mcp MCP server

Always refer to the official documentation for the most accurate and up-to-date information.