G-Search MCP

1<div align="center">
2  <img src="https://github.com/jae-jae/g-search-mcp/raw/main/icon.svg" width="120" height="120" alt="g-search-mcp Logo" />
3</div>
4 
5# G-Search MCP
6 
7A powerful MCP server for Google search that enables parallel searching with multiple keywords simultaneously.
8 
9> This project is modified from [google-search](https://github.com/web-agent-master/google-search).
10 
11> 🌟 **Recommended**: [OllaMan](https://ollaman.com/) - Powerful Ollama AI Model Manager.
12 
13## Advantages
14 
15- **Parallel Searching**: Supports searching with multiple keywords on Google simultaneously, improving search efficiency
16- **Browser Optimization**: Opens multiple tabs in a single browser instance for efficient parallel searching
17- **Automatic Verification Handling**: Intelligently detects CAPTCHA and enables visible browser mode for user verification when needed
18- **User Behavior Simulation**: Simulates real user browsing patterns to reduce the possibility of detection by search engines
19- **Structured Data**: Returns structured search results in JSON format for easy processing and analysis
20- **Configurable Parameters**: Supports various parameter configurations such as search result limits, timeout settings, locale settings, etc.
21 
22## Quick Start
23 
24Run directly with npx:
25 
26```bash
27npx -y g-search-mcp
28```
29 
30First time setup - install the required browser by running the following command in your terminal:
31 
32```bash
33npx playwright install chromium
34```
35 
36### Debug Mode
37 
38Use the `--debug` option to run in debug mode (showing browser window):
39 
40```bash
41npx -y g-search-mcp --debug
42```
43 
44## Configure MCP
45 
46Configure this MCP server in Claude Desktop:
47 
48MacOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
49Windows: `%APPDATA%/Claude/claude_desktop_config.json`
50 
51```json
52{
53  "mcpServers": {
54    "g-search": {
55      "command": "npx",
56      "args": ["-y", "g-search-mcp"]
57    }
58  }
59}
60```
61 
62## Features
63 
64- `search` - Execute Google searches with multiple keywords and return results
65  - Uses Playwright browser to perform searches
66  - Supports the following parameters:
67    - `queries`: Array of search queries to execute (required parameter)
68    - `limit`: Maximum number of results to return per query, default is 10
69    - `timeout`: Page loading timeout in milliseconds, default is 60000 (60 seconds)
70    - `noSaveState`: Whether to avoid saving browser state, default is false
71    - `locale`: Locale setting for search results, default is en-US
72    - `debug`: Whether to enable debug mode (showing browser window), overrides the --debug flag in command line
73 
74**Example usage**:
75 
76```
77Use the search tool to search for "machine learning" and "artificial intelligence" on Google
78```
79 
80**Example response**:
81 
82```json
83{
84  "searches": [
85    {
86      "query": "machine learning",
87      "results": [
88        {
89          "title": "What is Machine Learning? | IBM",
90          "link": "https://www.ibm.com/topics/machine-learning",
91          "snippet": "Machine learning is a branch of artificial intelligence (AI) and computer science which focuses on the use of data and algorithms to imitate the way that humans learn, gradually improving its accuracy."
92        },
93        ...
94      ]
95    },
96    {
97      "query": "artificial intelligence",
98      "results": [
99        {
100          "title": "What is Artificial Intelligence (AI)? | IBM",
101          "link": "https://www.ibm.com/topics/artificial-intelligence",
102          "snippet": "Artificial intelligence leverages computers and machines to mimic the problem-solving and decision-making capabilities of the human mind."
103        },
104        ...
105      ]
106    }
107  ]
108}
109```
110 
111## Usage Tips
112 
113### Handling Special Website Scenarios
114 
115#### Adjusting Search Parameters
116 
117- **Search Result Quantity**: For more search results:
118 
119  ```
120  Please return the top 20 search results for each keyword
121  ```
122 
123  This will set the `limit: 20` parameter.
124 
125- **Increase Timeout Duration**: For slow loading situations:
126  ```
127  Please set the page loading timeout to 120 seconds
128  ```
129  This will adjust the `timeout` parameter to 120000 milliseconds.
130 
131#### Locale Settings Adjustment
132 
133- **Change Search Region**: Specify a different locale setting:
134  ```
135  Please use Chinese locale (zh-CN) for searching
136  ```
137  This will set the `locale: "zh-CN"` parameter.
138 
139### Debugging and Troubleshooting
140 
141#### Enable Debug Mode
142 
143- **Dynamic Debug Activation**: To display the browser window during a specific search operation:
144  ```
145  Please enable debug mode for this search operation
146  ```
147  This sets `debug: true` even if the server was started without the `--debug` flag.
148 
149## Installation
150 
151### Prerequisites
152 
153- Node.js 18 or higher
154- NPM or Yarn
155 
156### Install from Source
157 
1581. Clone the repository:
159 
160```bash
161git clone https://github.com/jae-jae/g-search-mcp.git
162cd g-search-mcp
163```
164 
1652. Install dependencies:
166 
167```bash
168npm install
169```
170 
1713. Install Playwright browser:
172 
173```bash
174npm run install-browser
175```
176 
1774. Build the server:
178 
179```bash
180npm run build
181```
182 
183## Development
184 
185### Auto Rebuild (Development Mode)
186 
187```bash
188npm run watch
189```
190 
191### Using MCP Inspector for Debugging
192 
193```bash
194npm run inspector
195```
196 
197## Related Projects
198 
199- [fetcher-mcp](https://github.com/jae-jae/fetcher-mcp): A powerful MCP server for fetching web page content using Playwright headless browser. Features intelligent content extraction, parallel processing, resource optimization, and more, making it an ideal tool for web content scraping.
200 
201## License
202 
203Licensed under the [MIT License](https://choosealicense.com/licenses/mit/)
204