# Google Custom Search Engine MCP Server
A Model Context Protocol server that provides search capabilities using a CSE (custom search engine). This server enables LLMs to provide a regular google search term and returns the found search results.
The tool only returns the results itself and not the content, the tool should be combined with other servers like [mcp-server-fetch](https://github.com/modelcontextprotocol/servers/tree/main/src/fetch) to extract the content from the search results.
You may also combine it with other tools to enable some kind of "deep search" or tool chaining in general.
**The free quota is 100 searches (1 tool call == 1 search) per day, if you don't want to set up billing and this is insufficient for your use case, you should consider using another server.**
## Available Tools
- `google_search` - Searches the custom search engine using the search term and returns a list of results containing the title, link and snippet of each result.
- `search_term` (string, required): The search term to search for, equaling the [query parameter](https://bit.ly/AllTheOperators) `q` in the usual Google search.
## Environment variables
- `API_KEY` (required): The API key for the custom search engine.
- `ENGINE_ID` (required): The engine ID for the custom search engine.
- `SERVICE_NAME` (required/optional): The name of the service, leave empty if you haven't changed the name (customsearch).
- `COUNTRY_REGION` (optional): Restricts search results to documents originating in a particular country. See [Country Parameter Values](https://developers.google.com/custom-search/docs/json_api_reference#countryCollections) for valid values.
- `GEOLOCATION` (optional, default "us"): The geolocation of the end-user performing the search. See [Geolocation Parameter Values](https://developers.google.com/custom-search/docs/json_api_reference#countryCodes) for valid values.
- `RESULT_LANGUAGE` (optional, default "lang_en"): The language of the search results. See [CSE Query parameters, lr](https://developers.google.com/custom-search/v1/reference/rest/v1/cse/list?apix=true#query-parameters) for valid values.
- `RESULT_NUM` (optional, default 10): The number of search results to return. Range from 1-10.
## CSE Setup
Creating a custom search engine is comparatively easy, completely free and can be done in under 5 minutes.
1. Go to https://console.cloud.google.com/ and create a new project. Call it "Claude CSE" for example.
2. Select the project and search for "Custom Search API" in the search bar.
3. Click on the search result and click on "Enable".
4. Click on the Credentials tab and create a new API key.
5. Go to https://programmablesearchengine.google.com to create a new custom search engine.
6. Create a new search engine and give it any name, the name doesn't correlate to SERVICE_NAME.
7. Select "Search the entire web" if you want a normal Google Search experience.
8. Click on "Create" and copy the engine id from the js code, or hit customize and get it from the overview.
9. You can optionally customize the search engine to your liking.
With the default quota, you will get 100 searches per day for free. A tool call only costs 1 search, even if you get 10 results for example.
## Installation
### Using uv (recommended)
When using [`uv`](https://docs.astral.sh/uv/) no specific installation is needed. We will
use [`uvx`](https://docs.astral.sh/uv/guides/tools/) to directly run *mcp-google-cse*.
### Using PIP
Alternatively you can install `mcp-google-cse` via pip:
```
pip install mcp-google-cse
```
After installation, you can run it as a script using:
```
python -m mcp-google-cse
```
## Configuration
### Configure for Claude app
Add to your `claude_desktop_config.json`:
#### Using uvx (use this if you don't know which one to choose)
```
"mcp-google-cse": {
"command": "uvx",
"args": ["mcp-google-cse"],
"env": {
"API_KEY": "",
"ENGINE_ID": ""
}
}
```
#### Using pip installation
```
"mcp-google-cse": {
"command": "python",
"args": ["-m", "mcp-google-cse"],
"env": {
"API_KEY": "",
"ENGINE_ID": ""
}
}
```
#### Running locally
```
"mcp-google-cse": {
"command": "uv",
"args": [
"--directory",
"{{Path to the cloned repo",
"run",
"mcp-google-cse"
],
"env": {
"API_KEY": "",
"ENGINE_ID": ""
}
}
```
### Example result
google_search("What is MCP after:2024-11-01")
Result:
```json
[
{
"title": "Can someone explain MCP to me? How are you using it? And what ...",
"link": "https://www.reddit.com/r/ClaudeAI/comments/1h55zxd/can_someone_explain_mcp_to_me_how_are_you_using/",
"snippet": "Dec 2, 2024 ... Comments Section ... MCP essentially allows you to give Claude access to various external systems. This can be files on your computer, an API, a browser, a ..."
},
{
"title": "Introducing the Model Context Protocol \\ Anthropic",
"link": "https://www.anthropic.com/news/model-context-protocol",
"snippet": "Nov 25, 2024 ... The Model Context Protocol (MCP) is an open standard for connecting AI assistants to the systems where data lives, including content repositories, ..."
},
{
"title": "3.5 Sonnet + MCP + Aider = Complete Game Changer : r ...",
"link": "https://www.reddit.com/r/ChatGPTCoding/comments/1hwn6qd/35_sonnet_mcp_aider_complete_game_changer/",
"snippet": "Jan 8, 2025 ... Really cool stuff. For those out of the loop here are some MCP servers. You can give your Claude chat (in the desktop version, or in a tool like Cline) ..."
},
{
"title": "Announcing Spring AI MCP: A Java SDK for the Model Context ...",
"link": "https://spring.io/blog/2024/12/11/spring-ai-mcp-announcement",
"snippet": "Dec 11, 2024 ... This SDK will enable Java developers to easily connect with an expanding array of AI models and tools while maintaining consistent, reliable integration ..."
},
{
"title": "Implementing a MCP server in Quarkus - Quarkus",
"link": "https://quarkus.io/blog/mcp-server/",
"snippet": "6 days ago ... The Model Context Protocol (MCP) is an emerging standard that enables AI models to safely interact with external tools and resources. In this tutorial, I'll ..."
},
{
"title": "mark3labs/mcp-go: A Go implementation of the Model ... - GitHub",
"link": "https://github.com/mark3labs/mcp-go",
"snippet": "Dec 18, 2024 ... A Go implementation of the Model Context Protocol (MCP), enabling seamless integration between LLM applications and external data sources and tools."
},
{
"title": "MCP enables Claude to Build, Run and Test Web Apps by Looking ...",
"link": "https://wonderwhy-er.medium.com/mcp-enable-claude-to-build-run-and-test-web-apps-using-screenshots-3ae06aea6c4a",
"snippet": "Dec 18, 2024 ... How to Replicate My Experiment on Your Machine. If you're ready to dive into setting up MCP for Claude, follow these steps: ... 2. Download the Project: ... 3."
},
{
"title": "MCP definition and meaning | Collins English Dictionary",
"link": "https://www.collinsdictionary.com/dictionary/english/mcp",
"snippet": "2 days ago ... 2 meanings: male chauvinist pig → informal, derogatory a man who exhibits male chauvinism Abbreviation: MCP.... Click for more definitions."
},
{
"title": "What is Anthropic's New MCP Standard and How Can It Improve ...",
"link": "https://dappier.medium.com/what-is-anthropics-new-mcp-standard-and-how-can-it-improve-your-ai-agent-be6f6c72eb6a",
"snippet": "Nov 26, 2024 ... Anthropic has released a new protocol, MCP, for connecting AI agents to data sets. This blog explores when and why developers might use MCP to improve their ..."
},
{
"title": "Mostafa Gharib on LinkedIn: What is MCP and how it works",
"link": "https://www.linkedin.com/posts/mostafa-gharib_what-is-mcp-and-how-it-works-activity-7274301560594026497-p_yq",
"snippet": "Dec 15, 2024 ... ... MCP Host can use. (Bonus: SDKs in Python and TypeScript make it easy to build these servers!) 2️⃣ MCP Clients These interact with MCP Servers via the protocol."
}
]
```
Raw data
{
"_id": null,
"home_page": null,
"name": "mcp-google-cse",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "Google CSE, Google Custom Search Engine, MCP, Model Context Protocol, Web Browsing",
"author": null,
"author_email": "Richard-Weiss <76665424+Richard-Weiss@users.noreply.github.com>",
"download_url": "https://files.pythonhosted.org/packages/e4/79/6aa2b8ec232a1b72587092fcf98b8d56c2cb27c301c5612a70325c5656d8/mcp_google_cse-0.1.3.tar.gz",
"platform": null,
"description": "# Google Custom Search Engine MCP Server\n\nA Model Context Protocol server that provides search capabilities using a CSE (custom search engine). This server enables LLMs to provide a regular google search term and returns the found search results.\n\nThe tool only returns the results itself and not the content, the tool should be combined with other servers like [mcp-server-fetch](https://github.com/modelcontextprotocol/servers/tree/main/src/fetch) to extract the content from the search results.\nYou may also combine it with other tools to enable some kind of \"deep search\" or tool chaining in general.\n\n**The free quota is 100 searches (1 tool call == 1 search) per day, if you don't want to set up billing and this is insufficient for your use case, you should consider using another server.**\n\n## Available Tools\n\n- `google_search` - Searches the custom search engine using the search term and returns a list of results containing the title, link and snippet of each result.\n - `search_term` (string, required): The search term to search for, equaling the [query parameter](https://bit.ly/AllTheOperators) `q` in the usual Google search.\n\n## Environment variables\n\n- `API_KEY` (required): The API key for the custom search engine.\n- `ENGINE_ID` (required): The engine ID for the custom search engine.\n- `SERVICE_NAME` (required/optional): The name of the service, leave empty if you haven't changed the name (customsearch).\n- `COUNTRY_REGION` (optional): Restricts search results to documents originating in a particular country. See [Country Parameter Values](https://developers.google.com/custom-search/docs/json_api_reference#countryCollections) for valid values.\n- `GEOLOCATION` (optional, default \"us\"): The geolocation of the end-user performing the search. See [Geolocation Parameter Values](https://developers.google.com/custom-search/docs/json_api_reference#countryCodes) for valid values.\n- `RESULT_LANGUAGE` (optional, default \"lang_en\"): The language of the search results. See [CSE Query parameters, lr](https://developers.google.com/custom-search/v1/reference/rest/v1/cse/list?apix=true#query-parameters) for valid values.\n- `RESULT_NUM` (optional, default 10): The number of search results to return. Range from 1-10.\n\n## CSE Setup\nCreating a custom search engine is comparatively easy, completely free and can be done in under 5 minutes.\n\n1. Go to https://console.cloud.google.com/ and create a new project. Call it \"Claude CSE\" for example.\n2. Select the project and search for \"Custom Search API\" in the search bar.\n3. Click on the search result and click on \"Enable\".\n4. Click on the Credentials tab and create a new API key.\n5. Go to https://programmablesearchengine.google.com to create a new custom search engine.\n6. Create a new search engine and give it any name, the name doesn't correlate to SERVICE_NAME.\n7. Select \"Search the entire web\" if you want a normal Google Search experience.\n8. Click on \"Create\" and copy the engine id from the js code, or hit customize and get it from the overview.\n9. You can optionally customize the search engine to your liking.\n\nWith the default quota, you will get 100 searches per day for free. A tool call only costs 1 search, even if you get 10 results for example.\n\n\n## Installation\n\n### Using uv (recommended)\n\nWhen using [`uv`](https://docs.astral.sh/uv/) no specific installation is needed. We will\nuse [`uvx`](https://docs.astral.sh/uv/guides/tools/) to directly run *mcp-google-cse*.\n\n### Using PIP\n\nAlternatively you can install `mcp-google-cse` via pip:\n\n```\npip install mcp-google-cse\n```\n\nAfter installation, you can run it as a script using:\n\n```\npython -m mcp-google-cse\n```\n\n## Configuration\n\n### Configure for Claude app\n\nAdd to your `claude_desktop_config.json`:\n\n\n#### Using uvx (use this if you don't know which one to choose)\n```\n\"mcp-google-cse\": {\n \"command\": \"uvx\",\n \"args\": [\"mcp-google-cse\"],\n \"env\": {\n \"API_KEY\": \"\",\n \"ENGINE_ID\": \"\"\n }\n}\n```\n\n\n#### Using pip installation\n\n```\n\"mcp-google-cse\": {\n \"command\": \"python\",\n \"args\": [\"-m\", \"mcp-google-cse\"],\n \"env\": {\n \"API_KEY\": \"\",\n \"ENGINE_ID\": \"\"\n }\n}\n```\n\n#### Running locally\n\n```\n \"mcp-google-cse\": {\n \"command\": \"uv\",\n \"args\": [\n \"--directory\",\n \"{{Path to the cloned repo\",\n \"run\",\n \"mcp-google-cse\"\n ],\n \"env\": {\n \"API_KEY\": \"\",\n \"ENGINE_ID\": \"\"\n }\n }\n```\n\n### Example result\ngoogle_search(\"What is MCP after:2024-11-01\")\nResult:\n```json\n[\n {\n \"title\": \"Can someone explain MCP to me? How are you using it? And what ...\",\n \"link\": \"https://www.reddit.com/r/ClaudeAI/comments/1h55zxd/can_someone_explain_mcp_to_me_how_are_you_using/\",\n \"snippet\": \"Dec 2, 2024 ... Comments Section ... MCP essentially allows you to give Claude access to various external systems. This can be files on your computer, an API, a browser, a ...\"\n },\n {\n \"title\": \"Introducing the Model Context Protocol \\\\ Anthropic\",\n \"link\": \"https://www.anthropic.com/news/model-context-protocol\",\n \"snippet\": \"Nov 25, 2024 ... The Model Context Protocol (MCP) is an open standard for connecting AI assistants to the systems where data lives, including content repositories, ...\"\n },\n {\n \"title\": \"3.5 Sonnet + MCP + Aider = Complete Game Changer : r ...\",\n \"link\": \"https://www.reddit.com/r/ChatGPTCoding/comments/1hwn6qd/35_sonnet_mcp_aider_complete_game_changer/\",\n \"snippet\": \"Jan 8, 2025 ... Really cool stuff. For those out of the loop here are some MCP servers. You can give your Claude chat (in the desktop version, or in a tool like Cline) ...\"\n },\n {\n \"title\": \"Announcing Spring AI MCP: A Java SDK for the Model Context ...\",\n \"link\": \"https://spring.io/blog/2024/12/11/spring-ai-mcp-announcement\",\n \"snippet\": \"Dec 11, 2024 ... This SDK will enable Java developers to easily connect with an expanding array of AI models and tools while maintaining consistent, reliable integration ...\"\n },\n {\n \"title\": \"Implementing a MCP server in Quarkus - Quarkus\",\n \"link\": \"https://quarkus.io/blog/mcp-server/\",\n \"snippet\": \"6 days ago ... The Model Context Protocol (MCP) is an emerging standard that enables AI models to safely interact with external tools and resources. In this tutorial, I'll ...\"\n },\n {\n \"title\": \"mark3labs/mcp-go: A Go implementation of the Model ... - GitHub\",\n \"link\": \"https://github.com/mark3labs/mcp-go\",\n \"snippet\": \"Dec 18, 2024 ... A Go implementation of the Model Context Protocol (MCP), enabling seamless integration between LLM applications and external data sources and tools.\"\n },\n {\n \"title\": \"MCP enables Claude to Build, Run and Test Web Apps by Looking ...\",\n \"link\": \"https://wonderwhy-er.medium.com/mcp-enable-claude-to-build-run-and-test-web-apps-using-screenshots-3ae06aea6c4a\",\n \"snippet\": \"Dec 18, 2024 ... How to Replicate My Experiment on Your Machine. If you're ready to dive into setting up MCP for Claude, follow these steps: ... 2. Download the Project: ... 3.\"\n },\n {\n \"title\": \"MCP definition and meaning | Collins English Dictionary\",\n \"link\": \"https://www.collinsdictionary.com/dictionary/english/mcp\",\n \"snippet\": \"2 days ago ... 2 meanings: male chauvinist pig \u2192 informal, derogatory a man who exhibits male chauvinism Abbreviation: MCP.... Click for more definitions.\"\n },\n {\n \"title\": \"What is Anthropic's New MCP Standard and How Can It Improve ...\",\n \"link\": \"https://dappier.medium.com/what-is-anthropics-new-mcp-standard-and-how-can-it-improve-your-ai-agent-be6f6c72eb6a\",\n \"snippet\": \"Nov 26, 2024 ... Anthropic has released a new protocol, MCP, for connecting AI agents to data sets. This blog explores when and why developers might use MCP to improve their ...\"\n },\n {\n \"title\": \"Mostafa Gharib on LinkedIn: What is MCP and how it works\",\n \"link\": \"https://www.linkedin.com/posts/mostafa-gharib_what-is-mcp-and-how-it-works-activity-7274301560594026497-p_yq\",\n \"snippet\": \"Dec 15, 2024 ... ... MCP Host can use. (Bonus: SDKs in Python and TypeScript make it easy to build these servers!) 2\ufe0f\u20e3 MCP Clients These interact with MCP Servers via the protocol.\"\n }\n]\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "An MCP server for searching a custom Google search engine.",
"version": "0.1.3",
"project_urls": {
"Homepage": "https://github.com/Richard-Weiss/mcp-google-cse",
"Issues": "https://github.com/Richard-Weiss/mcp-google-cse/issues"
},
"split_keywords": [
"google cse",
" google custom search engine",
" mcp",
" model context protocol",
" web browsing"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "65d6314f45df97f21b12594cbd1fe7faac425d0da02a369225f56f46aa28eceb",
"md5": "895b787fb32e0e0882e434a774f0ff37",
"sha256": "b0789d357d3ea209aa075a88a5850f0e6371c83e48351a61b38052b63229113c"
},
"downloads": -1,
"filename": "mcp_google_cse-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "895b787fb32e0e0882e434a774f0ff37",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 6921,
"upload_time": "2025-01-19T13:26:07",
"upload_time_iso_8601": "2025-01-19T13:26:07.546085Z",
"url": "https://files.pythonhosted.org/packages/65/d6/314f45df97f21b12594cbd1fe7faac425d0da02a369225f56f46aa28eceb/mcp_google_cse-0.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e4796aa2b8ec232a1b72587092fcf98b8d56c2cb27c301c5612a70325c5656d8",
"md5": "ab267206cbdeed1e1aacd2d45c398e1c",
"sha256": "02a30da951ecf3bfd04318dac5a192fa00b6ea7cb4159b930884b0a905f20239"
},
"downloads": -1,
"filename": "mcp_google_cse-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "ab267206cbdeed1e1aacd2d45c398e1c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 24413,
"upload_time": "2025-01-19T13:26:08",
"upload_time_iso_8601": "2025-01-19T13:26:08.707907Z",
"url": "https://files.pythonhosted.org/packages/e4/79/6aa2b8ec232a1b72587092fcf98b8d56c2cb27c301c5612a70325c5656d8/mcp_google_cse-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-19 13:26:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Richard-Weiss",
"github_project": "mcp-google-cse",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "mcp-google-cse"
}
JSON
