# 🔌 MCP Server: Web Search Tool (FastMCP + Serper)

A lightweight, Claude-ready **MCP (Model Context Protocol) server** that wraps the [Serper.dev](https://serper.dev) Google Search API using Python, LangChain, and FastMCP.

This server exposes a structured, LLM-callable tool that performs a Google search and returns a filtered list of results along with a summary answer.



## 🚀 Features

- ✅ LLM-ready tool with structured input/output
- ✅ Works out-of-the-box with **Claude Desktop**, **ChatGPT**, or any **MCP-compatible agent**
- ✅ Built using [FastMCP](https://github.com/epfml/fastmcp)
- ✅ Real-world API integration via `GoogleSerperAPIWrapper`
- ✅ Easy to extend with more tools



## 📦 Requirements

- Python 3.10+
- A free [Serper.dev API key](https://serper.dev/)
- Optional: [Claude Desktop](https://www.anthropic.com/index/claude-desktop) for local tool calling
- Optional: [MCP Inspector](https://github.com/epfml/mcp-inspector) for manual testing



## 🔧 Installation

1. Clone the repo:
   ```
   git clone https://github.com/vikrambhat2/mcp-server-web-search.git
   cd mcp-server-web-search
```

2. Install dependencies:

   ```
   pip install -r requirements.txt
   ```

3. Set environment variables in a `.env` file:

   ```
   SERPER_API_KEY=your_serper_api_key_here
   PORT=10000
   ```

4. Run the server:

   ```
   python server.py
   ```

---

## 🔍 Tool Overview

This MCP server exposes a single tool: `google_search_tool`.

### 📤 Input

```json
{
  "input": "Your search query string"
}
```

### 📥 Output

```json
{
  "results": [
    {
      "title": "Result Title",
      "link": "https://...",
      "snippet": "Brief description"
    },
    ...
  ],
  "answer": "Concise answer generated by Serper"
}
```

---

## 🧪 Testing

### ✅ With `curl`

```bash
curl -X POST http://localhost:10000/api/tools/google_search_tool \
     -H "Content-Type: application/json" \
     -d '{"input": "latest AI trends 2025"}'
```

### 🧪 With Claude Desktop

1. Open **Claude Desktop** → `Settings → Toolcalling`

2. Add your MCP server:

   ```json
   {
     "mcpServers": {
       "googleSearch": {
         "url": "http://localhost:10000/mcp",
         "streaming": true
       }
     }
   }
   ```

3. Ask Claude something like:

   > "Use the `google_search_tool` to find top remote AI conferences in 2025."

### 🧰 With MCP Inspector (GUI)

1. Install MCP Inspector:

   ```bash
   pip install mcp-inspector
   mcp-inspector
   ```

2. Visit `http://localhost:8080`

3. Paste in `http://localhost:10000/mcp`

4. Explore your tool, prompt, and test it with real inputs.

---

## 🌐 Deployment (Optional)

You can deploy this server for free using [Render](https://render.com):

1. Push this project to a GitHub repo
2. Create a new **Web Service** on Render
3. Add build/start commands:

   * Build: `pip install -r requirements.txt`
   * Start: `python app.py`
4. Add environment variables:

   * `SERPER_API_KEY`
   * `PORT=10000`
5. Your server will be live at:
   `https://yourproject.onrender.com/mcp`

You can now plug it into Claude or your agents remotely.

---

## 📁 File Structure

```
├── app.py               # Main MCP server script
├── .env                 # API key and port config
├── requirements.txt     # Python dependencies
└── README.md            # This file
```

---

## 📚 References

* 🔌 [FastMCP](https://github.com/epfml/fastmcp)
* 🔍 [Serper.dev](https://serper.dev/)
* 🧪 [MCP Inspector](https://github.com/epfml/mcp-inspector)
* 🤖 [Claude + MCP Guide](https://www.weavely.ai/blog/claude-mcp)



## 🛠 Maintainer

Built by [@vikrambhat2](https://github.com/ikrambhat2)
Pull requests and forks welcome!