Flutter Inspector MCP Server: AI-Powered Debug & Real-Time Optimize

Flutter Inspector MCP Server for AI-Powered Development

GitHub Repository

🔍 A powerful Model Context Protocol (MCP) server that connects your Flutter apps with AI coding assistants like Cursor, Claude, and Cline.

This project is a work in progress and not all methods (mostly Flutter Inspector related) are implemented yet.

However, two methods are tested with Flutter:

• screenshot
• get_root_widget

Currently Flutter works with MCP server via forwarding server. Please see Architecture for more details.

Some of other methods are not tested - they may work or not. Please use with caution. It is possible that the most methods will be removed from the MCP server later to focus solely on Flutter applications and maybe Jaspr.

!!WARNING!!

ALL DUMPS TOOLS ARE VERY HEAVY OPERATION and can easily overload context window of AI agent. Please use them with extreme caution.

🚀 Quick Start

Prerequisites

• Node.js (v14 or later)
• A Flutter app running in debug mode
• One of: Cursor, Claude, or Cline AI assistant

Installation from GitHub

For developers who want to contribute to the project or run the latest version directly from source, follow these steps:

1. Clone the repository:

   git clone https://github.com/Arenukvern/mcp_flutter

cd flutter-inspector

2. Install and build dependencies:

   make install

This command installs all necessary dependencies listed in package.json and then builds MCP server and forwarding server.

3. Start forwarding server:

   make forward

4. Add DevTools Flutter Extension to Flutter App:

   flutter pub add --dev devtools_mcp_extension

5. Start your Flutter app in debug mode

! Current workaround for security reasons is to run with --disable-service-auth-codes. If you know how to fix this, please let me know!

    flutter run --debug --observatory-port=8181 --enable-vm-service --disable-service-auth-codes

6. 🛠️ Add Flutter Inspector to your AI tool

Note for Local Development (GitHub Install):

If you installed the Flutter Inspector from GitHub and built it locally, you need to adjust the paths in the AI tool configurations to point to your local build/index.js file. Refer to the "Installation from GitHub" section for instructions on cloning and building the project.

Cline Setup

1. Add to your `.cline/config.json`:
    
            {
      "mcpServers": {
        "flutter-inspector": {
          "command": "node",
          "args": [
            "/path/to/your/cloned/flutter-inspector/mcp_server/build/index.js"
          ],
          "env": {
            "PORT": "3334",
            "LOG_LEVEL": "info"
          },
          "disabled": false
        }
      }
    }
    

2. Restart Cline
3. The Flutter inspector will be automatically available in your conversations

Cursor Setup

1. Open Cursor's settings
2. Go to the Features tab
3. Under "Model Context Protocol", add the server:
    
            {
      "mcpServers": {
        "flutter-inspector": {
          "command": "node",
          "args": [
            "/path/to/your/cloned/flutter-inspector/mcp_server/build/index.js"
          ],
          "env": {},
          "disabled": false,
          "autoApprove": []
        }
      }
    }
    

4. Restart Cursor
5. Open Agent Panel (cmd + L on macOS)
6. You're ready! Try commands like "analyze my Flutter app's widget tree"

Claude Setup

1. Add to your Claude configuration file:
    
            {
      "mcpServers": {
        "flutter-inspector": {
          "command": "node",
          "args": [
            "/path/to/your/cloned/flutter-inspector/mcp_server/build/index.js"
          ],
          "env": {
            "PORT": "3334",
            "LOG_LEVEL": "info"
          },
          "disabled": false
        }
      }
    }
    

2. Restart Claude
3. The Flutter inspector tools will be automatically available

🎯 What You Can Do (Hopefully)

• Analyze Widget Trees : Get detailed information about your Flutter app's structure
• Inspect Navigation : See current routes and navigation state
• Debug Layout Issues : Understand widget relationships and properties

🔧 Configuration Options

Environment Variables (.env)

PORT=3334              # Server port (default: 3334)
LOG_LEVEL=info        # Logging level (error, warn, info, debug)

Command Line Arguments

--port, -p     # Server port
--stdio        # Run in stdio mode (default: true)
--log-level    # Set logging level
--help         # Show help

Port Configuration

All Flutter Inspector tools automatically connect to the default Flutter debug port (8181). You only need to specify a port if:

• You're running Flutter on a different port
• You have multiple Flutter instances running
• You've configured a custom debug port

Example usage:

// Default port (8181)
{
  "name": "debug_dump_render_tree"
}

// Custom port
{
  "name": "debug_dump_render_tree",
  "arguments": {
    "port": 8182
  }
}

🔧 Troubleshooting

1. Connection Issues

* Ensure your Flutter app is running in debug mode
* Verify the port matches in both Flutter app and inspector
* Check if the port is not being used by another process

2. AI Tool Not Detecting Inspector

* Restart the AI tool after configuration changes
* Verify the configuration JSON syntax
* Check the tool's logs for connection errors

📚 Available Tools

All tools default to using port 8181 if no port is specified. You can override this by providing a specific port number.

Utility Methods (Not Direct RPC Calls)

These are helper methods that provide additional functionality beyond direct Flutter RPC calls:

• get_active_ports: Lists all Flutter/Dart processes listening on ports
• get_supported_protocols: Retrieves supported protocols from a Flutter app
• get_vm_info: Gets detailed VM information from a running Flutter app
• get_extension_rpcs: Lists all available extension RPCs in the Flutter app

Debug Methods (ext.flutter.debug*)

Direct RPC methods for debugging Flutter applications:

• debug_dump_render_tree: Dumps the render tree structure
• debug_dump_layer_tree: Dumps the layer tree for rendering analysis
• debug_dump_semantics_tree: Dumps the semantics tree for accessibility analysis
• debug_paint_baselines_enabled: Toggles baseline paint debugging
• debug_dump_focus_tree: Dumps the focus tree for input handling analysis

Inspector Methods (ext.flutter.inspector.*)

Direct RPC methods for inspecting Flutter widget trees and layout:

• inspector_screenshot: Takes a screenshot of the Flutter app

DartIO Methods (ext.dart.io.*)

Direct RPC methods for Dart I/O operations:

• dart_io_get_version: Gets Flutter version information

Method Categories

1. Direct RPC Methods These methods map directly to Flutter's extension RPCs:

* All methods prefixed with `debug_`, `inspector_`, or `dart_io_`
* Each method corresponds to a specific Flutter RPC endpoint
* Parameters and return values match Flutter's specifications

2. Utility Methods These are helper methods that provide additional functionality:

* Process discovery (`get_active_ports`)
* Protocol inspection (`get_supported_protocols`)
* VM interaction (`get_vm_info`)
* RPC discovery (`get_extension_rpcs`)

Method Naming Convention

All methods follow a consistent naming pattern:

• Utility methods: descriptive_name
• Debug methods: debug_*
• Inspector methods: inspector_*
• DartIO methods: dart io *
• Stream methods: stream_*

Each method name indicates its category and functionality, making it easier to understand its purpose and capabilities.

Method Documentation Format

Each method includes:

• Clear description of functionality
• Required and optional parameters
• Return value format
• Category indication (RPC vs Utility)
• Corresponding Flutter RPC endpoint (if applicable)

For detailed implementation instructions, see the "Implementing New RPC Methods" section.

🔧 Implementing New RPC Methods

Step-by-Step Guide

1. Add RPC Method Definition

   // In src/index.ts, add to appropriate group in FlutterRPC

const FlutterRPC = {
  GroupName: {
    METHOD_NAME: createRPCMethod(RPCPrefix.GROUP, "methodName"),
    // ... other methods
  },
};

2. Add Tool Definition

   // In ListToolsRequestSchema handler

{
  name: "method_name",
  description: "Clear description of what the method does",
  inputSchema: {
    type: "object",
    properties: {
      port: {
        type: "number",
        description: "Port number where the Flutter app is running (defaults to 8181)",
      },
      // Add other parameters if needed
      paramName: {
        type: "string", // or boolean, number, etc.
        description: "Parameter description",
      }
    },
    required: ["paramName"], // List required parameters
  }
}

3. Implement Handler

   // In CallToolRequestSchema handler

case "method_name": {
  const port = handlePortParam();
  // Get and validate parameters if any
  const { paramName } = request.params.arguments as { paramName: string };
  if (!paramName) {
    throw new McpError(
      ErrorCode.InvalidParams,
      "paramName parameter is required"
    );
  }
  // Call the RPC method
  return wrapResponse(
    this.invokeFlutterExtension(port, FlutterRPC.GroupName.METHOD_NAME, {
      paramName,
    })
  );
}

Implementation Checklist

1. Method Definition

* [ ] Add to appropriate group in `FlutterRPC`
* [ ] Use correct `RPCPrefix`
* [ ] Follow naming convention

2. Tool Definition

* [ ] Add clear description
* [ ] Define all parameters
* [ ] Mark required parameters
* [ ] Add port parameter
* [ ] Document parameter types

3. Handler Implementation

* [ ] Add case in switch statement
* [ ] Handle port parameter
* [ ] Validate all parameters
* [ ] Add error handling
* [ ] Use proper types
* [ ] Return wrapped response

4. Testing

* [ ] Verify method works in debug mode
* [ ] Test with different parameter values
* [ ] Test error cases
* [ ] Test with default port

Example Implementation

// 1. Add RPC Method
const FlutterRPC = {
  Inspector: {
    GET_WIDGET_DETAILS: createRPCMethod(RPCPrefix.INSPECTOR, "getWidgetDetails"),
  }
};

// 2. Add Tool Definition
{
  name: "get_widget_details",
  description: "Get detailed information about a specific widget",
  inputSchema: {
    type: "object",
    properties: {
      port: {
        type: "number",
        description: "Port number where the Flutter app is running (defaults to 8181)",
      },
      widgetId: {
        type: "string",
        description: "ID of the widget to inspect",
      }
    },
    required: ["widgetId"],
  }
}

// 3. Implement Handler
case "get_widget_details": {
  const port = handlePortParam();
  const { widgetId } = request.params.arguments as { widgetId: string };
  if (!widgetId) {
    throw new McpError(
      ErrorCode.InvalidParams,
      "widgetId parameter is required"
    );
  }
  await this.verifyFlutterDebugMode(port);
  return wrapResponse(
    this.invokeFlutterExtension(port, FlutterRPC.Inspector.GET_WIDGET_DETAILS, {
      widgetId,
    })
  );
}

Common Patterns

1. Parameter Validation

* Always validate required parameters
* Use TypeScript types for type safety
* Throw `McpError` with clear messages

2. Error Handling

* Use try-catch blocks for async operations
* Verify Flutter debug mode when needed
* Handle connection errors

3. Response Wrapping

* Use `wrapResponse` for consistent formatting
* Handle both success and error cases
* Format response data appropriately

4. Port Handling

* Use `handlePortParam()` for port management
* Default to 8181 if not specified
* Validate port number

Notes for AI Agents

When implementing methods from todo.yaml:

1. Follow the step-by-step guide above
2. Use the example implementation as a template
3. Ensure all checklist items are completed
4. Add proper error handling and parameter validation
5. Follow the common patterns section
6. Test the implementation thoroughly

For each new method:

1. Check the method's group (UI, DartIO, Inspector, etc.)
2. Determine required parameters from method name and context
3. Implement following the standard patterns
4. Add appropriate error handling
5. Follow the existing code style

🤝 Contributing

Contributions are welcome! Please feel free to submit pull requests or report issues on the GitHub repository.

📖 Learn More

• Flutter DevTools Documentation
• Dart VM Service Protocol
• Flutter DevTools RPC Constants (I guess and hope they are correct:))

📄 License

MIT - Feel free to use in your projects!

---

Flutter and Dart are trademarks of Google LLC.