kimtth/mcp-aoai-web-browsing

A Playwright browsing application with Azure OpenAI/OpenAI, plus focused examples
of MCP v1/v2, OAuth, and interactive MCP Apps.
1. Original browsing application — Azure OpenAI/OpenAI integration, setup and client connections.
2. MCP v1 and v2 samples — browser tools and local OAuth flows.
3. MCP Apps samples — interactive tool-response UIs built with Prefab.
1. Web browsing MCP application
A local browsing application with a Tkinter chat UI and an MCP-to-LLM bridge.
- The original server uses the standalone fastmcp package; Playwright controls
a visible Chromium browser and keeps the current page between tool calls.
- The local client_bridge implementation adapts MCP
tool definitions to OpenAI Chat Completions function calling. It supports an
in-process FastMCP server or an external stdio server.
- The GUI uses Azure OpenAI. Python callers can configure the bridge for standard
OpenAI, but the original browser server separately initializes its own Azure
client for the selector-extraction tool.
Setup and run
Requirements: Python **3.13 or newer**, Tkinter, a graphical desktop session,
and uv. The commands
below use uv to manage this project's environment; MCP itself does not require
a particular Python package manager. Run them from the repository root.
1. Copy .env.template to a local .env file, keeping the
template intact. Configure an existing Azure OpenAI deployment that supports
Chat Completions tool calling:
The API version is needed for the legacy Azure endpoint, not the /openai/v1
path described below. Keep .env out of source control; it is gitignored.
2. Install the Python dependencies and the Chromium browser binary:
On Linux, Playwright may also require system dependencies; see its
installation guide. Tkinter must
be available in the selected Python installation.
3. Launch the GUI in the project environment:
The root dependency declarations use minimum versions, not
compatibility caps. The inspected environment uses FastMCP 3.2.0 and MCP SDK
1.27.0; this is not a guarantee that a fresh resolution of newer major versions
will work. Keep the learning samples in their separate environments.
Azure v1 endpoint and model parameters
For an endpoint ending in /openai/v1, set AZURE_OPEN_AI_ENDPOINT to the full
URL and AZURE_OPEN_AI_DEPLOYMENT_MODEL to an existing deployment name. This
path uses the OpenAI-compatible client and does not require an API version.
Use AZURE_OPEN_AI_API_KEY, or supply a short-lived Entra token through the
process environment variable AZURE_OPENAI_AD_TOKEN when the key is unset.
Tokens are not refreshed automatically; renew them before launching and never
commit them to a file.
Using with External Clients
External clients start the original server over stdio. Complete the setup above
first. The server loads the repository's .env and still requires Azure
configuration at startup, even if the host uses a different model provider.
Do not put credentials in shared MCP JSON configuration.
Click to expand - Claude Code, VS Code
Claude Desktop / Claude Code
- **Claude Desktop:** open **Settings > Developer > Edit Config** to edit
claude_desktop_config.json, following the
local-server guide.
- **Claude Code:** add the entry to .mcp.json at the project root for
project scope, not
.claude/mcp.json. Local and user scopes are managed separately by Claude Code.
Merge this entry into the existing configuration. Replace the directory with
the absolute repository path (Windows paths can use forward slashes). Using
uv's --directory avoids relying on a client-specific cwd field.
If the desktop client cannot find uv, set command to its absolute executable
path. Restart Claude Desktop after saving; in Claude Code, review project-server
approval and connection status with /mcp.
VS Code
Merge into .vscode/mcp.json in your workspace, following the