OpenAI WebSearch MCP Server for Python

Overview

The OpenAI WebSearch MCP Server for Python is a lightweight Model Context Protocol (MCP) server that exposes a simple HTTP API to run web-based queries using OpenAI’s web_search capability. It lets developer applications delegate live web lookups to a local service that returns structured results suitable for tool-enabled language models, agents, or any system that needs on-demand web retrieval integrated with LLM contexts.

Running a local MCP server isolates search logic from your application, centralizes configuration (API keys, rate limits, caching), and provides an MCP-compatible interface so you can plug the server into agent frameworks or custom LLM toolchains. This is useful when you want controlled, auditable web access for assistants, RAG (retrieval-augmented generation) workflows, or search-driven automation.

GitHub: https://github.com/ConechoAI/openai-websearch-mcp

Features

• Built-in OpenAI web_search integration for fetching up-to-date web results.
• MCP-compatible HTTP API designed to act as a tool provider for agents and LLMs.
• Lightweight Python implementation that is easy to deploy locally or in containers.
• Simple environment-based configuration (OPENAI_API_KEY, port).
• JSON input/output suitable for programmatic consumption and chaining.
• Basic input sanitization and structured response format ready for downstream consumption.

Installation / Configuration

Clone the repository and install dependencies. The example uses pip and a typical Python project layout.

# clone repository
git clone https://github.com/ConechoAI/openai-websearch-mcp.git
cd openai-websearch-mcp

# install dependencies (use a virtualenv)
pip install -r requirements.txt

Set the required environment variables (at minimum the OpenAI API key):

export OPENAI_API_KEY="sk-..."
export MCP_PORT=8080      # optional, default port used by the server
export MCP_HOST=0.0.0.0   # optional

Start the server (example runs a simple ASGI server with uvicorn):

uvicorn server:app --host ${MCP_HOST:-0.0.0.0} --port ${MCP_PORT:-8080}

If the project includes a dockerfile, you can build and run via Docker:

docker build -t openai-websearch-mcp .
docker run -e OPENAI_API_KEY="$OPENAI_API_KEY" -p 8080:8080 openai-websearch-mcp

Configuration reference (common environment variables):

Available Tools / Resources

The server exposes the following primary tool:

• openai.web_search
  • Purpose: Run a web query and return structured link snippets, titles, summary/extracts and metadata suitable for context augmentation.
  • Input: a plain-text query string and optional query parameters (max results, freshness).
  • Output: JSON array of search results with fields such as title, snippet, url, and metadata.

Typical endpoints (examples — check the repository README for exact routes):

• GET /health — basic health check
• GET /tools — list available MCP tools
• POST /tools/web_search/run — run the web_search tool
• POST /mcp/execute — generic MCP execute endpoint (tool name + input)

Example request format (generic):

{
  "tool": "openai.web_search",
  "input": "latest news on renewable energy in 2026",
  "options": { "max_results": 5 }
}

Example simplified response:

{
  "tool": "openai.web_search",
  "results": [
    {
      "title": "Renewable energy milestones in 2026",
      "snippet": "Countries X and Y reached new capacity...",
      "url": "https://example.com/renewables-2026",
      "source": "example.com",
      "published": "2026-02-03"
    }
  ]
}

Use Cases

• Agent tool for conversational assistants

  • Configure your agent framework to call the MCP server’s web_search tool whenever the model requests a live web lookup. Responses are returned as structured JSON so the agent can cite sources or synthesize answers.

• Retrieval-augmented generation (RAG)

  • Use web_search to collect relevant URLs and excerpts, then feed the most relevant snippets into the LLM prompt to produce up-to-date answers that reference current web content.

• Content monitoring and summarization

  • Schedule queries for topical monitoring (e.g., competitor news or product mentions) and aggregate results downstream for trend analysis or automated alerting.

• Enrichment for knowledge workflows

  • Enrich internal documents with external context by programmatically fetching supporting evidence via the MCP server before indexing or summarization.

Quick Example (Python client)

A minimal example using requests to call the server:

import requests

MCP_URL = "http://localhost:8080/tools/web_search/run"
payload = {
    "input": "How will electric vehicle adoption grow in 2026?",
    "options": {"max_results": 3}
}
resp = requests.post(MCP_URL, json=payload)
resp.raise_for_status()
data = resp.json()
for r in data.get("results", []):
    print(r["title"], "-", r["url"])

Next Steps

• Review the code and README in the GitHub repo for exact API routes and advanced configuration.
• Add authentication, rate-limiting, or caching if you plan to expose the server publicly.
• Integrate the MCP server into your agent or orchestration layer to start providing live web context to your models.