wkwebview-mcp
Supports debugging WKWebViews in Capacitor hybrid iOS apps, exposing console logs, network requests, DOM content, screenshots, and JavaScript evaluation for the app's web views.
Supports Flutter iOS apps using webview_flutter or flutter_inappwebview, enabling inspection and control of embedded WKWebViews.
Supports Cordova/Ionic hybrid iOS apps, allowing agents to inspect, drive, and debug the WKWebViews embedded in the app.
Targets iOS apps running in simulators or on USB-connected devices, providing tools to inspect and interact with every WKWebView in the app.
Supports React Native apps using react-native-webview, letting agents inspect and interact with embedded WKWebViews.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
wkwebview-mcp
Let your AI coding agent debug the WKWebViews inside your iOS app.
An MCP server that gives Claude Code, Cursor, VS Code, Windsurf and any other MCP client the console, network log, DOM and a JavaScript prompt of every web view in your app, in the simulator or on a USB-connected device. It works for native apps and for hybrid apps built with Capacitor, Cordova/Ionic, React Native (react-native-webview) and Flutter (webview_flutter), because all of them render with WKWebView.
You: Tapping "Subscribe" in the app does nothing. Find out why.
Agent: click {text: "Subscribe"}
→ Clicked <button#subscribe> "Subscribe" at 314,406
Warning: <div#cookie-banner.banner-ghost> is on top of it at that point,
so a real tap would hit that instead.
Agent: The cookie banner fades to opacity 0 but stays in the layout and on top of the
newsletter card. Removing it after the animation (or pointer-events: none) fixes it.Why
Debugging a web view inside an app has meant Safari's Web Inspector: excellent, but manual, so an agent can't use it.
Automation tools don't fill the gap. safaridriver and WebDriver only drive Safari itself, not the web views in your app. Proxies
built on the remote Web Inspector protocol (ios-webkit-debug-proxy, Appium's remote debugger) are tied to private
protocol details that change between iOS releases.
wkwebview-mcp takes a different route. A small Swift package in your debug build serves the app's web views
on 127.0.0.1:9333, and this MCP server talks to it. No private APIs, no proxy, no jailbreak, nothing in release builds.
┌──────────────┐ stdio ┌───────────────┐ HTTP 127.0.0.1:9333 ┌──────────────────────────────┐
│ Claude Code, │ ──────▶ │ wkwebview-mcp │ ────────────────────▶ │ Your app (debug build) │
│ Cursor, … │ (MCP) │ (Node, npx) │ │ WebViewMCP Swift package │
└──────────────┘ └───────────────┘ │ ├─ WKWebView #1 ◀─ bridge │
│ └─ WKWebView #2 ◀─ bridge │
└──────────────────────────────┘Related MCP server: Safari Web Inspector Bridge
What your agent can do
Tool | What it does |
| Find running apps (and their web views) across simulators and forwarded devices |
| Read the page as text, as HTML, or as a list of interactive elements with refs |
| Drive the page. |
| Run any JavaScript (async, |
|
|
| fetch and XHR with status, headers and bodies, plus documents, scripts, images and styles with timing |
| Page loads, redirects, failed loads, |
| Load a URL, reload, back, forward |
| The web view as WebKit renders it, or the whole simulator screen with the native UI around it |
| Everything else you need to aim the above |
Logs are recorded all the time, not only while a client is connected. So you can reproduce a bug by hand and then ask the agent what happened.
Quick start
1. Add the Swift package
In Xcode: File → Add Package Dependencies…, enter https://github.com/sdyalcin/wkwebview-mcp, and add the
WebViewMCP library to your app target. With Package.swift:
.package(url: "https://github.com/sdyalcin/wkwebview-mcp", from: "0.1.0")2. Start it in debug builds
import WebViewMCP
// In your App init or application(_:didFinishLaunchingWithOptions:)
#if DEBUG
WebViewMCP.start()
#endifThat's all. Every WKWebView in the app is picked up just before its first load. Optionally give one a name the agent can refer to:
#if DEBUG
WebViewMCP.register(checkoutWebView, name: "checkout")
#endif3. Add the MCP server to your client
Claude Code
claude mcp add wkwebview -- npx -y wkwebview-mcpCursor, Windsurf, Claude Desktop and other clients that use an mcpServers JSON file:
{
"mcpServers": {
"wkwebview": {
"command": "npx",
"args": ["-y", "wkwebview-mcp"]
}
}
}VS Code (.vscode/mcp.json):
{
"servers": {
"wkwebview": {
"type": "stdio",
"command": "npx",
"args": ["-y", "wkwebview-mcp"]
}
}
}4. Run the app and ask
Run a debug build in the simulator, then ask your agent things like "what errors does the checkout page log?", "why does the login request fail?" or "click Pay and tell me what the payment iframe sends back".
Check what the server can see at any time:
npx -y wkwebview-mcp doctorHybrid frameworks
WebViewMCP.start() registers web views automatically, so in each framework you only add the package to the
iOS project and call start() where the app launches. These setups follow each framework's standard iOS project.
They haven't all been tried in real apps yet, so if one needs more than shown here, please open an issue.
Capacitor / Ionic. Open ios/App/App.xcworkspace (or App.xcodeproj), add the package to the App target, and in
AppDelegate.swift:
import WebViewMCP
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
#if DEBUG
WebViewMCP.start()
#endif
return true
}Cordova. Add the package to the app target in platforms/ios, then in AppDelegate.m:
@import WebViewMCP;
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
#if DEBUG
[WebViewMCP start];
#endif
self.viewController = [[MainViewController alloc] init];
return [super application:application didFinishLaunchingWithOptions:launchOptions];
}React Native (react-native-webview). Add the package to the app target in ios/, then in AppDelegate.swift
(or [WebViewMCP start]; in an Objective-C AppDelegate.mm):
import WebViewMCP
#if DEBUG
WebViewMCP.start()
#endifFlutter (webview_flutter, flutter_inappwebview). Add the package to the Runner target in ios/Runner.xcworkspace, then
in AppDelegate.swift:
import WebViewMCP
override func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
#if DEBUG
WebViewMCP.start()
#endif
GeneratedPluginRegistrant.register(with: self)
return super.application(application, didFinishLaunchingWithOptions: launchOptions)
}Framework hooks that run whenever the native project is regenerated (cap sync, cordova prepare, expo prebuild)
can drop manual Xcode changes. If yours does, add the package and the start() call from a config plugin or hook.
Try it with the example app
Example/ has a SwiftUI app with two web views. The Playground tab is a local page with deliberate bugs: a
failing API call, a button covered by an invisible banner, a promise nobody handles and a payment iframe. The Browser
tab is a plain browser whose web view is never registered by hand.
open Example/WebViewMCPExample.xcodeprojRun it on a simulator, add the MCP server to your client, and ask "Why does Load profile fail in the playground?".
The project is generated from Example/project.yml with XcodeGen.
Physical devices
The server listens on the device's loopback interface. Forward the port over USB with iproxy from libimobiledevice:
brew install libimobiledeviceiproxy 9333 9333This route hasn't been tested on hardware yet. Reports are welcome.
Several apps or simulators at once
Each app takes the first free port from 9333 to 9342, and the MCP server scans that range. Tools act on the first app
found unless you pass app (a port, bundle id, app name or simulator name). They act on the web view that is on screen
unless you pass webview (wv1, wv2, … or a name you registered).
Configuration
var configuration = WebViewMCP.Configuration()
configuration.port = 9333 // first port to try
configuration.portAttempts = 10 // how many ports to try
configuration.registerAllWebViews = true // false: only web views you register()
configuration.maxBodyCharacters = 65_536 // network bodies are truncated beyond this
configuration.makeInspectable = true // also allow Safari's Web Inspector (iOS 16.4+)
WebViewMCP.start(configuration)The MCP server reads WKWEBVIEW_MCP_HOST, WKWEBVIEW_MCP_PORT and WKWEBVIEW_MCP_PORT_RANGE if you change the defaults.
HTTP API
The MCP server is a thin client. You can call the app directly from scripts or tests:
curl -s localhost:9333/webviewscurl -s localhost:9333/eval -d '{"code": "document.title"}'curl -s "localhost:9333/console?level=error"Routes: GET /info, /webviews, /frames, /console, /network, /network/entry?id=, /navigation,
/snapshot and POST /eval, /navigate, /clear. Every route takes an optional webview.
How it works
Bridge script. A
WKUserScriptinjected at document start into every frame, in the page's own JavaScript world. It wrapsconsole,fetch,XMLHttpRequestandhistory, listens for errors, rejections and CSP violations, and reads Resource Timing for everything else. Every wrapper calls the original and returns its result, so the page sees no difference.JavaScript. Runs through
callAsyncJavaScriptin the page world, in the main frame or the iframe you choose. Results are serialized in the page, so DOM nodes, cycles and BigInts come back readable.Automatic registration. The package exchanges the implementations of WKWebView's
load…methods anddidMoveToWindow, so it can register a web view before its first page starts. These are ordinary public methods, and each one calls straight through to WebKit.Server. A small HTTP/1.1 server on Network.framework, bound to
127.0.0.1.
Security
Anyone who can reach the port can run JavaScript in your web views, so:
Only start it in debug builds. Wrap
WebViewMCP.start()in#if DEBUG.It binds to the loopback interface. On a simulator that is your Mac's loopback; on a device it is reachable only through a USB port forward.
Requests that carry an
Originheader are refused. So are requests whoseHostis not loopback. This stops a web page open on your Mac from driving the app, including through DNS rebinding.
Limitations
clickandfilldispatch DOM events. They don't produce real touches, so native gesture recognizers and hit-testing are not involved. When a real tap matters, tap the simulator (Claude Code's iOS Simulator tools,xcrun simctl, XCUITest).clickwarns when another element would take the real tap.There are no breakpoints or stepping.
isInspectableis set, so Safari's Web Inspector can attach next to it.The network log covers what the page does through
fetchand XHR in detail. Documents, scripts, images and styles get URL and timing only. Requests made natively (URLSession) or by service workers are not seen.A failed page load (DNS, offline, TLS) shows up as
loadFailedinnavigation_history. The error code itself stays with the app's navigation delegate.iOS 15 or later.
Development
swift testnpm testswift test runs the package against a real WKWebView on macOS. npm test runs the MCP server against a stand-in app.
License
MIT
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Let your AI agent control real iPhones: screenshots, tap, swipe, type and open apps.
Drive real devices from your AI Coding tool. Embed a client SDK (Unity, Godot, Flutter, iOS/macOS, Android, React Native, Web) in your app, then capture screenshots, traverse the UI tree, inject taps and key events, and run automated test tasks on the physical device over a secure relay.
Cloud iPhones and Macs with Xcode for AI agents: build, run and test iOS apps, use the screen.
Live browser debugging for AI assistants — DOM, console, network via MCP.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables AI assistants to control iOS simulators through WebDriverAgent, supporting taps, swipes, typing, screenshots, recording, and app actions with a real-time dashboard for visual feedback.36Apache 2.0
- AlicenseAqualityDmaintenanceAn MCP server that gives AI agents the ability to inspect, observe, and automate WKWebViews on connected iOS devices via Safari Web Inspector.141MIT
- AlicenseNot gradedqualityDmaintenanceGives AI agents the ability to interact with iOS simulators through 21+ tools for mobile app testing.10,447 npmMIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to inspect and verify mobile UI hierarchies, nodes, styles, screenshots, and runtime attributes of iOS apps in simulators or on USB devices.2Apache 2.0