salhmed/mcp_server_web_search

🌐 MCP Web Search Server

An example MCP (Model Context Protocol) HTTP server that exposes:

• Web search via the Tavily API
• Employee info (mocked, no database)

It's a beginner-friendly template to learn how to build and expose MCP tools.
Environment and dependencies are managed with uv.

📦 Requirements

• Python 3.13+
• uv (recommended) — pipx install uv or see uv docs
• A Tavily API key (free tier available)

📂 Project Structure

MCP_WEB_SEARCH_SERVER/
├─ .env.example          # Example environment variables
├─ .gitignore
├─ main.py               # Hello World entry
├─ mcp-server-http.py    # MCP HTTP server with tools
├─ pyproject.toml        # Project metadata & deps
├─ README.md
└─ uv.lock               # uv lockfile (optional to commit)

🚀 Setup

1) Clone

git clone https://github.com/salhmed/mcp_server_web_search.git
cd mcp_server_web_search

2) Install deps (with uv)

uv sync

This creates/uses a local .venv/ and installs dependencies from pyproject.toml (and uv.lock if present).

🔑 Configure Environment

Copy the example env file:

cp .env.example .env

Put your Tavily key in .env:

TAVILY_API_KEY=your_api_key_here

▶️ Run

Hello World

uv run python main.py
# -> Hello from mcp-web-search-server!

Start the MCP HTTP Server

uv run python mcp-server-http.py

The server listens on:

http://0.0.0.0:23000

(You can also run with your system Python if the venv is active: python mcp-server-http.py.)

🛠️ Tools Exposed

1) get_employee_info(name: str) -> Dict

Returns a mock employee record for the provided name.

Example output:

{
  "name": "Alice",
  "salary": 43000,
  "department": "Engineering",
  "location": "New York",
  "age": 30
}

2) web_search(query: str) -> List[Dict]

Performs a web search using the Tavily API and returns a list of results.

Example input:

{ "query": "python uv packaging" }

Example output (shape):

[
  { "title": "UV: Fast Python package manager", "link": "https://example.com/uv" },
  { "title": "How to use uv with Python", "link": "https://example.com/guide" }
]

Requires a valid TAVILY_API_KEY in .env.

🧪 Quick CLI Tests (MCP)

If you have the MCP CLI installed (via mcp[cli]):

Ping the server:

mcp ping http://0.0.0.0:23000

Call a tool:

mcp call http://0.0.0.0:23000 get_employee_info '{"name":"Alice"}'
mcp call http://0.0.0.0:23000 web_search '{"query":"open source mcp server"}'

It's very recommended to use mcp inspector to test the server if you had installed the node js in your laptop

npx @modelcontextprotocol/inspector

🧭 How It Fits Together

flowchart LR
  A[Client / MCP-aware App] <---> B[MCP HTTP Server<br/>FastMCP @ :23000]
  B -->|tool: web_search| C[(Tavily API)]
  B -->|tool: get_employee_info| D[(Mock Data)]

❗ Troubleshooting

KeyError: 'TAVILY_API_KEY'
Ensure .env exists and contains TAVILY_API_KEY=.... The server uses python-dotenv to load it.

Cannot bind to port 23000
Another process may be using it. Change the port in mcp-server-http.py:

mcp = FastMCP("mcp-http-server", host="0.0.0.0", port=NEW_PORT)

Import errors
Make sure you ran uv sync, or use uv run to execute scripts with the managed environment.

🤝 Contributing

PRs and issues are welcome!

Ideas: better error handling, richer search result schema, more example tools, tests.

✨ Notes

• The employee tool is demo-only (no DB).
• The web search tool needs a valid Tavily key.
• Using uv is recommended for reproducible and fast installs.