AgentQL MCP Server

1# AgentQL MCP Server
2 
3This is a Model Context Protocol (MCP) server that integrates [AgentQL](https://agentql.com)'s data extraction capabilities.
4 
5## Features
6 
7### Tools
8 
9- `extract-web-data` - extract structured data from a given 'url', using 'prompt' as a description of actual data and its fields to extract.
10 
11## Installation
12 
13To use AgentQL MCP Server to extract data from web pages, you need to install it via npm, get an API key from our [Dev Portal](https://dev.agentql.com), and configure it in your favorite app that supports MCP.
14 
15### Install the package
16 
17```bash
18npm install -g agentql-mcp
19```
20 
21### Configure Claude
22 
23- Open Claude Desktop **Settings** via `⌘`+`,` (don't confuse with Claude Account Settings)
24- Go to **Developer** sidebar section
25- Click **Edit Config** and open `claude_desktop_config.json` file
26- Add `agentql` server inside `mcpServers` dictionary in the config file
27- Restart the app
28 
29```json title="claude_desktop_config.json"
30{
31  "mcpServers": {
32    "agentql": {
33      "command": "npx",
34      "args": ["-y", "agentql-mcp"],
35      "env": {
36        "AGENTQL_API_KEY": "YOUR_API_KEY"
37      }
38    }
39  }
40}
41```
42 
43Read more about MCP configuration in Claude [here](https://modelcontextprotocol.io/quickstart/user).
44 
45### Configure VS Code
46 
47For one-click installation, click one of the install buttons below:
48 
49[![Install with NPX in VS Code](https://img.shields.io/badge/VS_Code-NPM-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=agentql&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22agentql-mcp%22%5D%2C%22env%22%3A%7B%22AGENTQL_API_KEY%22%3A%22%24%7Binput%3AapiKey%7D%22%7D%7D&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22apiKey%22%2C%22description%22%3A%22AgentQL+API+Key%22%2C%22password%22%3Atrue%7D%5D) [![Install with NPX in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-NPM-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=agentql&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22agentql-mcp%22%5D%2C%22env%22%3A%7B%22AGENTQL_API_KEY%22%3A%22%24%7Binput%3AapiKey%7D%22%7D%7D&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22apiKey%22%2C%22description%22%3A%22AgentQL+API+Key%22%2C%22password%22%3Atrue%7D%5D&quality=insiders)
50 
51#### Manual Installation
52 
53Click the install buttons at the top of this section for the quickest installation method. For manual installation, follow these steps:
54 
55Add the following JSON block to your User Settings (JSON) file in VS Code. You can do this by pressing `Ctrl + Shift + P` and typing `Preferences: Open User Settings (JSON)`.
56 
57```json
58{
59  "mcp": {
60    "inputs": [
61      {
62        "type": "promptString",
63        "id": "apiKey",
64        "description": "AgentQL API Key",
65        "password": true
66      }
67    ],
68    "servers": {
69      "agentql": {
70        "command": "npx",
71        "args": ["-y", "agentql-mcp"],
72        "env": {
73          "AGENTQL_API_KEY": "${input:apiKey}"
74        }
75      }
76    }
77  }
78}
79```
80 
81Optionally, you can add it to a file called `.vscode/mcp.json` in your workspace. This will allow you to share the configuration with others.
82 
83```json
84{
85  "inputs": [
86    {
87      "type": "promptString",
88      "id": "apiKey",
89      "description": "AgentQL API Key",
90      "password": true
91    }
92  ],
93  "servers": {
94    "agentql": {
95      "command": "npx",
96      "args": ["-y", "agentql-mcp"],
97      "env": {
98        "AGENTQL_API_KEY": "${input:apiKey}"
99      }
100    }
101  }
102}
103```
104 
105### Configure Cursor
106 
107- Open **Cursor Settings**
108- Go to **MCP > MCP Servers**
109- Click **+ Add new MCP Server**
110- Enter the following:
111  - Name: "agentql" (or your preferred name)
112  - Type: "command"
113  - Command: `env AGENTQL_API_KEY=YOUR_API_KEY npx -y agentql-mcp`
114 
115Read more about MCP configuration in Cursor [here](https://docs.cursor.com/context/model-context-protocol).
116 
117### Configure Windsurf
118 
119- Open **Windsurf: MCP Configuration Panel**
120- Click **Add custom server+**
121- Alternatively you can open `~/.codeium/windsurf/mcp_config.json` directly
122- Add `agentql` server inside `mcpServers` dictionary in the config file
123 
124```json title="mcp_config.json"
125{
126  "mcpServers": {
127    "agentql": {
128      "command": "npx",
129      "args": ["-y", "agentql-mcp"],
130      "env": {
131        "AGENTQL_API_KEY": "YOUR_API_KEY"
132      }
133    }
134  }
135}
136```
137 
138Read more about MCP configuration in Windsurf [here](https://docs.codeium.com/windsurf/mcp).
139 
140### Validate MCP integration
141 
142Give your agent a task that will require extracting data from the web. For example:
143 
144```text
145Extract the list of videos from the page https://www.youtube.com/results?search_query=agentql, every video should have a title, an author name, a number of views and a url to the video. Make sure to exclude ads items. Format this as a markdown table.
146```
147 
148> [!TIP]
149> In case your agent complains that it can't open urls or load content from the web instead of using AgentQL, try adding "use tools" or "use agentql tool" hint.
150 
151## Development
152 
153Install dependencies:
154 
155```bash
156npm install
157```
158 
159Build the server:
160 
161```bash
162npm run build
163```
164 
165For development with auto-rebuild:
166 
167```bash
168npm run watch
169```
170 
171If you want to try out development version, you can use the following config instead of the default one:
172 
173```json
174{
175  "mcpServers": {
176    "agentql": {
177      "command": "/path/to/agentql-mcp/dist/index.js",
178      "env": {
179        "AGENTQL_API_KEY": "YOUR_API_KEY"
180      }
181    }
182  }
183}
184```
185 
186> [!NOTE]
187> Don't forget to remove the default AgentQL MCP server config to not confuse Claude with two similar servers.
188 
189## Debugging
190 
191Since MCP servers communicate over stdio, debugging can be challenging. We recommend using the [MCP Inspector](https://github.com/modelcontextprotocol/inspector), which is available as a package script:
192 
193```bash
194npm run inspector
195```
196 
197The Inspector will provide a URL to access debugging tools in your browser.
198