MCP Aoai Web Browsing

What kimtth/mcp-aoai-web-browsing MCP server does

kimtth/mcp-aoai-web-browsing MCP server connects an MCP browser tool to Azure OpenAI or standard OpenAI. The included server is built with FastMCP and uses Playwright for browser interaction. The documented tool, playwright_navigate, accepts a URL and optional timeout and page-load waiting behavior, then navigates the browser to that address.

The repository also includes a client-side bridge. It retrieves MCP tool definitions, reshapes them into the format expected by OpenAI function calling, and routes model-selected calls back to the MCP server. This makes the project useful both as a browser server for external MCP clients and as a sample Python application with its own LLM loop.

How it works

A local MCP server exposes the browser functionality through the FastMCP application in server/browser_navigator_server.py. The bridge can connect to that application directly in the same process or launch it as an external server over stdio. Passing the server object directly to the bridge is used to maintain a stable connection in the in-process arrangement.

For clients that manage their own model loop, the bridge can return tool metadata and execute a named tool with arguments. The README demonstrates a direct call to playwright_navigate with a URL. External clients can instead start the server from an MCP configuration file and handle model interaction themselves.

Setup and configuration

The documented development workflow uses uv. Rename .env.template to .env, provide the Azure OpenAI settings, install the project dependencies with uv sync, and start the sample interface with python chatgui.py. The sample launches a browser and navigates to a URL.

Azure OpenAI configuration uses AZURE_OPEN_AI_ENDPOINT, AZURE_OPEN_AI_API_KEY, AZURE_OPEN_AI_DEPLOYMENT_MODEL, and AZURE_OPEN_AI_API_VERSION. The bridge can also use standard OpenAI by selecting its OpenAI configuration helper and setting OPENAI_API_KEY and OPENAI_MODEL.

External MCP clients start the application with uv run fastmcp run ./server/browser_navigator_server.py:app. The examples show this setup for Claude Desktop, Claude Code, and VS Code. A Python program can configure the same stdio command through MCPServerConfig and manage its lifetime with BridgeManager.

Tools and capabilities

The documented capabilities include:

• Exposing Playwright browser navigation through MCP.
• Navigating to a supplied URL with playwright_navigate.
• Passing a navigation timeout and wait_until value.
• Converting MCP tools into OpenAI function-calling definitions.
• Executing tools directly from Python through the bridge.
• Connecting to MCP servers in-process or over stdio.

Limitations and notes

The supplied material documents navigation rather than a complete browser automation tool catalog. It does not establish support for a hosted endpoint, OAuth, or a packaged one-command installation. Running the server requires a local Python and uv setup, plus credentials for either Azure OpenAI or standard OpenAI, depending on the selected configuration. The external-client examples use repository-relative paths, so the configured working directory must point to the checked-out project.