Agno MCP Search

An MCP server that exposes an Agno agent with Google Gemini reasoning and Serper web search — usable from Claude Desktop, Cursor, or any MCP-compatible client, plus a local Streamlit UI for testing.

<p align="left"> <img src="https://img.shields.io/badge/python-3.10%2B-blue" alt="Python 3.10+" /> <img src="https://img.shields.io/badge/license-MIT-green" alt="MIT License" /> <img src="https://img.shields.io/badge/protocol-MCP-purple" alt="Model Context Protocol" /> <img src="https://img.shields.io/badge/agent-Agno-orange" alt="Agno" /> <img src="https://img.shields.io/badge/model-Gemini-red" alt="Gemini" /> <img src="https://img.shields.io/badge/status-alpha-yellow" alt="Alpha" /> </p>

---

Overview

Modern chat assistants like Claude and ChatGPT are powerful, but their knowledge is frozen at training time. This project bridges that gap by giving them a fresh, agent-driven search capability — delivered through the Model Context Protocol (MCP).

The MCP server exposes a single tool, search(query). Behind the tool sits an Agno agent that:

1. Receives a natural-language query,
2. Uses Serper to run a Google Search,
3. Reasons over the top results with Google Gemini,
4. Returns a markdown-formatted summary to the calling MCP client.

The same server is also drivable from a local Streamlit UI, which is handy for demos and debugging without needing an MCP client running.

Why this project exists

• Learn MCP by building it. MCP is quickly becoming the de-facto standard for tool-augmented LLM apps. A small, honest reference server is more useful than a giant framework demo.
• Prove the agent-in-tool pattern. Rather than exposing raw search results, the tool exposes an agent. The client asks a question; the server does the retrieval-and-reason loop and returns a synthesized answer.
• Stay swappable. Gemini, Serper, and Agno are all replaceable by design — the boundary is the search MCP tool, not the LLM or search vendor.

Architecture

flowchart LR
    subgraph Client["MCP Client (Claude Desktop / Cursor / Streamlit UI)"]
        UI[User query]
    end

    subgraph Server["FastMCP Server (agentic_mcp.server)"]
        TOOL["search(query)"]
        AGENT[Agno Agent]
        GEMINI[[Gemini LLM]]
        SERPER[[Serper Search]]
    end

    UI -- MCP call --> TOOL
    TOOL --> AGENT
    AGENT -- reasoning --> GEMINI
    AGENT -- tool use --> SERPER
    SERPER -- results --> AGENT
    GEMINI -- answer --> AGENT
    AGENT -- markdown --> TOOL
    TOOL -- MCP response --> UI

Technology stack

Layer	Library / Service	Purpose
Protocol	FastMCP	MCP server framework — exposes tools over stdio
Agent framework	Agno	Agent loop, tool orchestration, markdown formatting
LLM	Google Gemini	Reasoning and answer synthesis
Search	Serper	Google Search API
Local UI	Streamlit	Browser-based demo client
Config	python-dotenv	Loads secrets from .env
Test / lint	pytest, ruff	Test runner and linter

Folder structure

agno-mcp-search/
├── agentic_mcp/               # Application package
│   ├── __init__.py
│   ├── config.py              # Env loading & validation
│   ├── agent.py               # Agno agent factory
│   ├── server.py              # FastMCP server + search tool
│   └── ui/
│       └── streamlit_app.py   # Streamlit demo UI
├── tests/                     # pytest suite
│   ├── test_config.py
│   └── test_server.py
├── scripts/
│   └── verify_env.py          # One-shot health checks
├── docs/
│   ├── Architecture.md
│   ├── MCP.md
│   └── Installation.md
├── screenshots/               # (add your captures here)
├── .github/workflows/ci.yml   # Lint + test on every PR
├── .env.example
├── .gitignore
├── LICENSE                    # MIT
├── README.md
├── CONTRIBUTING.md
├── CODE_OF_CONDUCT.md
├── SECURITY.md
├── CHANGELOG.md
├── pyproject.toml             # Modern packaging + tool config
├── requirements.txt
└── requirements-dev.txt

Installation

Prerequisites

• Python 3.10+
• A Google Gemini API key
• A Serper API key
• Optional: uv for faster installs

Setup with pip

# 1. Clone
git clone https://github.com/kishansri/agno-mcp-search.git
cd agno-mcp-search

# 2. Create a venv
python -m venv venv
source venv/bin/activate            # macOS/Linux
venv\Scripts\Activate.ps1           # Windows PowerShell

# 3. Install (dev mode)
pip install -e ".[dev]"

# 4. Configure secrets
cp .env.example .env                # macOS/Linux
Copy-Item .env.example .env         # Windows PowerShell
# then edit .env and paste your keys

Setup with uv

git clone https://github.com/kishansri/agno-mcp-search.git
cd agno-mcp-search
uv venv
uv pip install -e ".[dev]"
cp .env.example .env

Environment variables

Variable	Required	Default	Purpose
GOOGLE_API_KEY	Yes	—	Gemini access
SERPER_API_KEY	Yes	—	Serper Google Search
GEMINI_MODEL_ID	No	gemini-3.1-flash-lite	Override the default Gemini model
LOG_LEVEL	No	INFO	Log verbosity written to logs/mcp-server.log

Running

1. Verify your setup

python scripts/verify_env.py all

This runs env, Gemini, Serper, and end-to-end Agno checks. It never prints your keys.

2. Run the MCP server

python -m agentic_mcp.server
# or, if installed via pip:
agentic-mcp

3. Run the Streamlit UI

streamlit run agentic_mcp/ui/streamlit_app.py

Open http://localhost:8501 and enter a query.

4. Install into Claude Desktop

fastmcp install claude-desktop agentic_mcp/server.py \
  --with agno --with google-genai --with fastmcp --with python-dotenv \
  --env-file .env

Restart Claude Desktop. The search tool will appear in the tool picker.

How the agent works

1. Tool receives a query. search(query: str) is invoked by the MCP client.
2. Input is validated. Empty or overly long queries are rejected before spending API credits.
3. Agent runs the reasoning loop. Agno decides when to call Serper and how many times.
4. Gemini synthesizes the answer. Search snippets are handed to Gemini for summarization.
5. Result is returned as markdown. The MCP client renders it as-is.

Features

• ✅ Single-tool MCP server (search)
• ✅ Agno agent with Gemini reasoning + Serper search
• ✅ Streamlit local UI
• ✅ Fail-fast config validation
• ✅ Logging to file (stdout stays clean for MCP protocol)
• ✅ pytest suite with mocked external calls
• ✅ CI-ready (.github/workflows/ci.yml)

Known limitations

• Single-agent design. No multi-agent planner/reviewer split (yet — see roadmap).
• No caching. Repeated queries re-hit Gemini and Serper.
• No RAG or memory. Every query is stateless.
• No auth on the MCP tool. Fine for local use; do not expose over the network without adding auth.
• Preview models may break. If you set GEMINI_MODEL_ID to a preview alias and Google deprecates it, the tool will fail until you change the env var.

Roadmap

See CHANGELOG.md for released versions and docs/Architecture.md for planned multi-agent design.

Short version:

• v0.2 — Response caching, richer tool description, structured JSON output option.
• v0.3 — Optional Planner + Researcher + Reviewer multi-agent flow.
• v1.0 — Docker image, CI/CD, guardrails, observability.

Contributing

Contributions welcome. See CONTRIBUTING.md.

Security

Please read SECURITY.md before reporting vulnerabilities.

License

MIT — see LICENSE.

Screenshots

Screenshots live in screenshots/. Suggested captures:

• Streamlit UI with a sample query and response
• Claude Desktop showing the search tool available
• Terminal running verify_env.py all with all green checks

---

Built with FastMCP · Agno · Gemini · Serper.