Buoy MCP
Buoy MCP lets an agent read a running React Native or Flutter app, tap its screen and inspect the network
- 693 ★ on the repository
- Last commit
Broad access
Why this level
- Taps the screen, types and drives the simulator or phone, and with Pro changes storage values, Redux and Zustand state, the clock, location and app permissions
- Reads network request bodies and storage values, which can hold tokens and personal data
- The init command overwrites the buoy entry in MCP config files and copies a skill over matching files
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add mcp/buoy-mcpDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- Taps the screen, types and drives the simulator or phone, and with Pro changes storage values, Redux and Zustand state, the clock, location and app permissions
- Reads network request bodies and storage values, which can hold tokens and personal data
- The init command overwrites the buoy entry in MCP config files and copies a skill over matching files
This is third-party code. Review the repository files before installing.
What it does
Buoy MCP connects the agent to a React Native or Flutter app running on a simulator or phone with the Buoy developer panel. The agent starts with list_devices, sees the connected devices and the tools each exposes, then reads events: network requests, state changes, route changes, storage writes. The agent drives the screen the way a person would. describe_screen reads what is shown; tap_element, native_tap, native_swipe and native_type tap, scroll and type; run_flow runs a chain of steps in one call and can save a passing flow into .buoy/flows. screenshot_component and screen_recording capture frames and video, get_console reads logs, and reload_app and navigate restart the app and jump to a route. A free account unlocks the basic tools and Buoy Optimize, with measurements of fps, CPU, memory and jank. Pro adds Zustand, Redux, Jotai and React Query state, storage values, request bodies and mocks, clock, location and permission changes, and the causes of slow screens. Every Saturday and Sunday a free account gets everything Pro does. The same package installs Buoy Web, where the agent works in its own Chrome tabs and no account is needed.
Who it is for. For React Native and Flutter developers who debug and profile their app with Claude Code, Cursor and other MCP clients.
Good fit when
- The agent has to walk a screen on a simulator, tap buttons and confirm a fix works: describe_screen and run_flow
- The bug lives in the network: get_network_requests lists requests with ids and get_network_request reads one in full
- The app is slow and you need measurements before and after a change with run_benchmark_batch and compare_reports
- You need to test offline or high-latency behaviour with network_conditions (React Native, development builds)
- A bug report needs a component screenshot or a screen recording
Not a fit when
- The app is native Swift or Kotlin: Buoy connects through packages inside a React Native or Flutter app
- You need to inspect a release build: sync is off there until you turn it on yourself
- You do not want an account on buoy.gg: the MCP needs a sign-in even on the free plan
- You need taps and screenshots of a simulator but the machine has no Xcode (iOS) or adb (Android): those tools depend on them
Example request
Run the app on the simulator, open the cart screen, tap Checkout and show me which network requests went out and what they returnedMCP
- Transport
- stdio
- Authentication
- OAuth
Environment variables
BUOY_VERIFY- Controls the reminder to verify a change on the device before calling it fixed; the example uses auto
Limitations
- Node.js 18 or newer and a Buoy account are required: buoy login does the sign-in. Without it the server looks for a key in the env files of the folder it runs from.
- When the agent calls a tool locked by the plan it gets a message that Pro is needed, and the request never reaches the app.
- Some capabilities work only in React Native, for example network_conditions and Redux state.
- A React Native app needs the @buoy-gg/external-sync package and the FloatingDevTools component; Flutter needs BuoyDevTools.
- The npx @latest configuration contacts the npm registry whenever the editor starts the server. If a private registry from .npmrc is unreachable, init installs a pinned local copy instead.
How to disable. Delete the buoy entry from .mcp.json, .cursor/mcp.json and .vscode/mcp.json, then restart the editor. The init command copies the buoy-optimize skill into the project, and that folder can be removed too. In the app, the Buoy panel goes away together with the @buoy-gg/external-sync package.
FAQ
How do I connect Buoy MCP to Claude Code?
In the app folder run npx --package=@buoy-gg/core buoy login, approve the sign-in in the browser and run npx -y @buoy-gg/mcp@latest init. The command writes the server into .mcp.json. After the editor restarts, ask the agent to call list_devices.
What does the free plan of Buoy MCP include?
Screen reading, taps and typing, run_flow, screenshots and recording, console logs, the network request list without bodies, the get_triage summary with storage key names and Buoy Optimize speed tests. State, storage values, request bodies and the causes of slow screens belong to Pro and are open to everyone on weekends.
Can the agent work with websites in Chrome?
Yes, the package includes Buoy Web: npx -y @buoy-gg/mcp@latest init --web adds a buoy-web server and then you install the Chrome extension. No account is needed. The agent works only in tabs it opened itself and never types passwords or card numbers.
Does Buoy MCP work with a real phone?
Yes. For a React Native app Buoy takes the broker address from Metro, and a phone usually finds it on its own. In Flutter you pass a socketUrl such as http://<lan-ip>:42831 to BuoyDevTools. Taps and screenshots from the computer need Xcode for iOS or adb for Android.
How do I update Buoy MCP?
Rerun npx -y @buoy-gg/mcp@latest init: the server entry is replaced and the buoy-optimize skill files are overwritten, so save your own edits to it first. The server checks npm once a day and adds a line about a newer version to the list_devices result.
Discussion
No questions or reviews yet.
Related
MCP serversGives an agent control of iOS simulators, Android emulators, TVs and Electron apps: taps, flows, profiling and React Native debugging
An MCP server to drive iOS and Android: simulators, emulators and real devices via accessibility trees and screenshots
Expo's official agent skills: building, deploying, updating and debugging Expo and EAS apps
Two skills for building mobile screens at top-app quality: studying real screens through the Appllama MCP and a strict bar for native Expo and React Native UI
The Flutter team's agent plugin: Flutter and Dart skills, the Dart MCP server and a hot reload rule for Claude Code, Cursor and Codex
The npx serve-sim command streams an iOS Simulator to the browser and lets an agent tap, swipe, type and replace the camera feed
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| Buoy MCP (this entry) | yes | OAuth | 693 | |
| agent-react-devtools | no | 252 | a CLI for the component tree, props, state and render profiling in React, with no screen taps and no Flutter | |
| Mobile MCP | no | not required | 10,126 | drives iOS and Android through the accessibility tree and screenshots and does not look inside the app for network or state |
README in short
The @buoy-gg/mcp README opens with a one-line install and a note that a free account gives the basic tools and Buoy Optimize while Pro adds the full set. A separate section covers Buoy Web, a mode for the agent to work in Chrome without an account. The remaining sections show techniques: reading the screen with native_inspect using simulator point coordinates, comparing a saved PNG with the live screen, and building a multi-step flow in run_flow. The detailed guide lives on buoy.gg and in docs/mcp.md in the repository.