Agentql MCP

🚀 AgentQL MCP Server

This is a Model Context Protocol (MCP) server that integrates the data extraction functionality of AgentQL.

✨ Features

Tools

• extract-web-data - Extract structured data from web pages based on a given 'url' and a 'prompt' that describes the actual data and its fields.

📦 Installation

To use the AgentQL MCP server for web data extraction, install it via npm, obtain an API key from our Developer Portal, and configure it in an MCP-supported application.

Install the Package

npm install -g agentql-mcp

Configure Claude

• Open Claude Desktop Settings via ⌘ + , (do not confuse it with Claude account settings).
• Navigate to the Developer sidebar section.
• Click Edit Configuration and open the claude_desktop_config.json file.
• Add the agentql server under the mcpServers dictionary in the configuration file.
• Restart the application.

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

Learn more about MCP configuration in Claude here.

Configure Cursor

• Open Cursor Settings.
• Navigate to MCP > MCP Servers.
• Click + Add New MCP Server.
• Enter the following information:
  • Name: "agentql" (or your preferred name)
  • Type: "command"
  • Command: env AGENTQL_API_KEY=YOUR_API_KEY npx -y agentql-mcp

Learn more about MCP configuration in Cursor here.

Configure Windsurf

• Open the Windsurf: MCP Configuration Panel.
• Click Add Custom Server +.
• Alternatively, you can directly open ~/.codeium/windsurf/mcp_config.json.
• Add the agentql server under the mcpServers dictionary in the configuration file.

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

Learn more about MCP configuration in Windsurf here.

Verify MCP Integration

Give your agent a task that requires extracting data from a web page. For example:

Extract the video list from the page https://www.youtube.com/results?search_query=agentql. Each video should include the title, author name, view count, and video URL. Ensure that advertisement items are excluded. Format it as a Markdown table.

💡 Usage Tip If your agent complains about being unable to open URLs or load content from web pages, try adding the "Use tools" or "Use agentql tools" prompt.

🔧 Development

Install dependencies:

npm install

Build the server:

npm run build

Develop with automatic rebuild:

npm run watch

If you want to try the development version, you can use the following configuration instead of the default one:

{
  "mcpServers": {
    "agentql": {
      "command": "/path/to/agentql-mcp/dist/index.js",
      "env": {
        "AGENTQL_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

⚠️ Important Note Don't forget to delete the default AgentQL MCP server configuration to avoid confusing Claude with two similar servers.

🐞 Debugging

Since MCP servers communicate via stdio, debugging can be challenging. We recommend using the MCP Inspector, which is available as a package script:

npm run inspector

The inspector will provide a URL to access the debugging tool in your browser.