npm package: @flutterpilot/mcp-server
Description: MCP server for AI interaction with Flutter debug apps
Author: FlutterPilot
Latest version: 0.1.0

# @flutterpilot/mcp-server

MCP server that lets AI assistants interact with Flutter apps running in debug mode. Connect Claude (or any MCP-compatible client) to a live Flutter app and let it see, navigate, and test your UI.

## What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) is an open standard that allows AI assistants to connect to external tools and data sources. An MCP server exposes **tools** (actions the AI can call) and **resources** (data the AI can read). This package is an MCP server that bridges the gap between AI assistants and Flutter apps.

## Installation

Install globally:

```bash
npm install -g @flutterpilot/mcp-server
```

Or run directly with npx (no install required):

```bash
npx @flutterpilot/mcp-server
```

## Configuration for Claude Desktop

Add the following to your Claude Desktop configuration file (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "flutter-pilot": {
      "command": "npx",
      "args": ["@flutterpilot/mcp-server"]
    }
  }
}
```

**Config file location:**
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

## Configuration for Claude Code

Add the MCP server to your Claude Code project settings:

```bash
claude mcp add flutter-pilot -- npx @flutterpilot/mcp-server
```

Or add it to your `.claude/settings.json` manually:

```json
{
  "mcpServers": {
    "flutter-pilot": {
      "command": "npx",
      "args": ["@flutterpilot/mcp-server"]
    }
  }
}
```

## Available Tools

### Connection

| Tool | Description | Params |
|---|---|---|
| `flutter_connect` | Connect to a running Flutter debug app via its VM service URI | `vmServiceUri` (string, required) |
| `flutter_disconnect` | Disconnect from the currently connected Flutter app | _(none)_ |

### Inspection

| Tool | Description | Params |
|---|---|---|
| `flutter_screenshot` | Take a screenshot of the Flutter app (returns PNG image) | _(none)_ |
| `flutter_widget_tree` | Get the widget tree as structured JSON | `maxDepth` (number, optional) |
| `flutter_semantics` | Get the semantics/accessibility tree as compact AI-friendly JSON | `maxDepth` (number, optional, default 20) |
| `flutter_interactive` | List all interactive widgets with positions and labels | _(none)_ |

### Interaction

| Tool | Description | Params |
|---|---|---|
| `flutter_tap` | Tap a widget by coordinates or finder | `x`, `y` (numbers) or `findBy` (`text`/`key`/`type`/`semantics`), `value` (string) |
| `flutter_enter_text` | Enter text into the focused text field | `text` (string, required) |
| `flutter_scroll` | Scroll at a position by a given delta | `x`, `y` (numbers, required), `dx` (number, optional), `dy` (number, required) |
| `flutter_long_press` | Long-press a widget by coordinates or finder | `x`, `y` (numbers) or `findBy`, `value` (string) |

### Development

| Tool | Description | Params |
|---|---|---|
| `flutter_hot_reload` | Trigger a hot reload (apply code changes, preserve state) | _(none)_ |
| `flutter_evaluate` | Evaluate a Dart expression in the running app | `expression` (string, required) |

## Available Resources

MCP resources provide data that the AI can read at any time without explicitly calling a tool.

| Resource URI | Name | Description |
|---|---|---|
| `flutter://app/widget-tree` | Flutter Widget Tree | The current widget tree of the connected app |
| `flutter://app/semantics` | Flutter Semantics Tree | The accessibility/semantics tree of the connected app |
| `flutter://app/interactive-widgets` | Flutter Interactive Widgets | All interactive widgets with their positions and labels |

## Example Conversation

Below is a realistic interaction between a user and Claude with the FlutterPilot MCP server configured:

> **User:** Connect to my Flutter app at ws://127.0.0.1:56789/ABCDEF=/ws

> **Claude:** _(calls `flutter_connect` with `vmServiceUri: "ws://127.0.0.1:56789/ABCDEF=/ws"`)_
>
> Connected to your Flutter app. I can see the flutter_pilot extensions are available, so all inspection and interaction tools are ready to use.

> **User:** Take a screenshot so I can see the current state

> **Claude:** _(calls `flutter_screenshot`)_
>
> Here is the current state of your app. I can see a counter app with a "You have pushed the button this many times: 0" message and a floating action button in the bottom right.

> **User:** Tap the + button

> **Claude:** _(calls `flutter_tap` with `findBy: "type"`, `value: "FloatingActionButton"`)_
>
> Tapped the FloatingActionButton. Let me take a screenshot to verify the result.
>
> _(calls `flutter_screenshot`)_
>
> The counter has incremented to 1. The tap was successful.

> **User:** What interactive widgets are on the screen?

> **Claude:** _(calls `flutter_interactive`)_
>
> There is one interactive widget on screen:
> - **FloatingActionButton** at position (351, 756) with the "+" icon

> **User:** Evaluate the current counter value in Dart

> **Claude:** _(calls `flutter_evaluate` with `expression: "MyHomePage.of(context).counter"`)_
>
> The current counter value is `1`.

## Prerequisites

1. **Flutter app with `flutter_pilot`**: Add the Dart package to your app and call `FlutterPilot.ensureInitialized()` in `main()`. See the [flutter_pilot Dart package](https://pub.dev/packages/flutter_pilot) for setup instructions.

2. **App running in debug mode**: Launch your app with `flutter run`. The VM service URI is printed in the console output:
   ```
   A Dart VM Service on Chrome is available at: ws://127.0.0.1:56789/ABCDEF=/ws
   ```

3. **Node.js >= 18**: Required to run the MCP server.

Without the `flutter_pilot` Dart package, only `flutter_screenshot` and `flutter_widget_tree` will work (they use Flutter's built-in inspector). All interaction tools (`flutter_tap`, `flutter_scroll`, `flutter_enter_text`, `flutter_long_press`) and `flutter_semantics` / `flutter_interactive` require the Dart package.

## How It Works

```
Claude (or AI) <--MCP--> @flutterpilot/mcp-server <--WebSocket--> Dart VM Service <--> flutter_pilot extensions
```

1. The MCP server starts on stdio and registers tools and resources with the AI client.
2. The AI calls `flutter_connect` with the Dart VM service URI.
3. The server establishes a WebSocket connection to the Dart VM and discovers the Flutter isolate.
4. Subsequent tool calls are translated into Dart VM service protocol requests and `flutter_pilot` extension calls.
5. Results (screenshots, widget trees, action confirmations) are returned to the AI.

## License

MIT