<languages/>
<translate>

<!--T:1-->
{{Macro
|Name=Macro Start MCP Bridge
|Icon=Macro_Start_MCP_Bridge.png
|Description=Start the MCP (Model Context Protocol) bridge server  which is part of the [https://github.com/spkane/freecad-robust-mcp-and-more FreeCAD Robust MCP server] which helps facilitate AI assistant integration with FreeCAD. Enables AI tools like Claude Code to control FreeCAD programmatically.
|Author=Sean P. Kane
|Version=0.5.0-beta
|Date=2026-01-05
|FCVersion=0.21+
|Download=[https://wiki.freecad.org/images/thumb/d/d7/Macro_Start_MCP_Bridge.png/48px-Macro_Start_MCP_Bridge.png ToolBar Icon]
|SeeAlso=[[Python_scripting_tutorial|Python Scripting Tutorial]]
}}

==Description== <!--T:2-->

<!--T:3-->
This macro starts the MCP (Model Context Protocol) bridge server which is part of the [https://github.com/spkane/freecad-robust-mcp-and-more FreeCAD Robust MCP server] on GitHub. This enables AI assistants like [https://claude.com/claude-code Claude Code] and other MCP-compatible clients to control FreeCAD programmatically.

<!--T:4-->
'''What is MCP?'''

The Model Context Protocol (MCP) is an open standard developed by Anthropic that allows AI assistants to interact with external tools and applications. With this bridge running, an AI assistant can:
* Create and manipulate FreeCAD documents
* Build 3D models using Part and PartDesign workbenches
* Execute Python code within FreeCAD's environment
* Export models to various formats (STEP, STL, 3MF, etc.)
* Query object properties and document state

<!--T:5-->
'''Server Ports:'''
* '''XML-RPC''' (port 9875): Compatible with neka-nat's original freecad-mcp implementation
* '''JSON-RPC Socket''' (port 9876): Modern protocol for MCP clients

<!--T:6-->
'''Key Features:'''
* Dual protocol support (XML-RPC and JSON-RPC)
* Full access to FreeCAD's Python API
* Safe code execution with result capture
* Console output streaming
* Works with Claude Code, and other MCP-compatible AI tools

==Usage== <!--T:7-->

<!--T:8-->
'''Prerequisites:'''
# Install the freecad-robust-mcp package from PyPI or GitHub
# Configure the macro with the correct project path (done automatically by the installer)

<!--T:9-->
'''Starting the Bridge:'''
# Open FreeCAD
# Run the macro from '''Macro → Macros → StartMCPBridge → Execute'''
# The console will show:
#: {{Code|code=
MCP Bridge started!
  - XML-RPC: localhost:9875
  - Socket: localhost:9876

You can now connect your MCP client (Claude Code, etc.) to FreeCAD.
}}

<!--T:10-->
'''Connecting an AI Client:'''

For Claude Code, add this to your MCP settings:
{{Code|code=
{
  "mcpServers": {
    "freecad": {
      "command": "freecad-mcp",
      "args": ["--mode", "xmlrpc"]
    }
  }
}
}}

==Requirements== <!--T:11-->

<!--T:12-->
* FreeCAD 0.21 or later
* Python 3.11+ (must match FreeCAD's bundled Python version)
* The freecad-robust-mcp package installed

==Installation== <!--T:13-->

<!--T:14-->
'''Method 1: Using the Installer Script'''

If you have the freecad-robust-mcp project cloned locally:
{{Code|code=
just install-bridge-macro
}}

This automatically:
* Copies the macro to your FreeCAD macro directory
* Injects the correct project path
* Sets up the icon

<!--T:15-->
'''Method 2: Manual Installation'''

# Install the freecad-robust-mcp package:
#: {{Code|code=
pip install freecad-robust-mcp
}}
# Download the macro file: [[Media:StartMCPBridge.FCMacro|StartMCPBridge.FCMacro]]
# Edit the macro and replace {{Incode|__PROJECT_PATH__}} with the actual path to the installed package
# Copy the file to your FreeCAD macro directory:
#* '''macOS''': {{FileName|~/Library/Application Support/FreeCAD/Macro/}}
#* '''Linux''': {{FileName|~/.local/share/FreeCAD/Macro/}}
#* '''Windows''': {{FileName|%APPDATA%/FreeCAD/Macro/}}

==Troubleshooting== <!--T:16-->

<!--T:17-->
'''Error: "MCP Bridge macro not properly installed"'''

The project path placeholder was not replaced during installation. Run:
{{Code|code=
just install-bridge-macro
}}

<!--T:18-->
'''Error: "Failed to import MCP Bridge module"'''

The freecad-robust-mcp package is not installed or not accessible. Ensure:
* The package is installed: {{Incode|pip install freecad-robust-mcp}}
* The project path in the macro points to the correct location

<!--T:19-->
'''Connection Issues'''

* Verify the bridge is running (check the FreeCAD console for startup messages)
* Ensure no firewall is blocking ports 9875 and 9876
* Try connecting with a simple test: {{Incode|curl http://localhost:9875}}

==Source Code== <!--T:20-->

<!--T:21-->
The full source code is hosted on GitHub:
* [https://github.com/spkane/freecad-robust-mcp-and-more/blob/main/macros/Start_MCP_Bridge/StartMCPBridge.FCMacro StartMCPBridge.FCMacro on GitHub]
* [https://github.com/spkane/freecad-robust-mcp-and-more GitHub Repository (freecad-robust-mcp-and-more)]

==Script== <!--T:22-->

<!--T:23-->
ToolBar Icon [[Image:Macro_Start_MCP_Bridge.png]]

</translate>

'''Macro_Start_MCP_Bridge.FCMacro'''

{{MacroCode|code=
"""FreeCAD Macro: Start MCP Bridge Server.

SPDX-License-Identifier: MIT
Copyright (c) 2025 Sean P. Kane (GitHub: spkane)

Start the MCP bridge server for AI assistant integration with FreeCAD.

Requirements:
    - FreeCAD 0.21 or later
    - freecad-mcp project installed and accessible

Usage:
    1. Install via: just install-bridge-macro
    2. Run the macro from: Macro -> Macros -> StartMCPBridge -> Execute
    3. Connect your MCP client (Claude Code, etc.) to the running bridge
"""

# FreeCAD Addon Manager metadata
__Name__ = "Start MCP Bridge"
__Comment__ = "Start the MCP bridge server for AI assistant integration with FreeCAD"
__Author__ = "Sean P. Kane"
__Version__ = "0.5.0-beta"
__Date__ = "2026-01-05"
__License__ = "MIT"
__Web__ = "https://github.com/spkane/freecad-robust-mcp-and-more"
__Wiki__ = "https://github.com/spkane/freecad-robust-mcp-and-more#readme"
__Icon__ = ""
__Help__ = "Run this macro to start the MCP bridge server on ports 9875 (XML-RPC) and 9876 (Socket). Connect your MCP client (Claude Code, etc.) to the running bridge."
__Status__ = "Beta"
__Requires__ = "FreeCAD 0.21+"
__Communication__ = "https://github.com/spkane/freecad-robust-mcp-and-more/issues"
__Files__ = ""

import sys

import FreeCAD


def start_mcp_bridge():
    """Start the MCP bridge server for AI assistant integration."""
    # The project path is injected during macro installation
    # This placeholder will be replaced with the actual path
    project_path = "__PROJECT_PATH__"

    if project_path == "__PROJECT_PATH__":
        FreeCAD.Console.PrintError(
            "MCP Bridge macro not properly installed.\n"
            "Please run: just install-bridge-macro\n"
        )
        return

    if project_path not in sys.path:
        sys.path.insert(0, project_path)

    try:
        # Import and start the plugin
        from freecad_mcp.freecad_plugin.server import FreecadMCPPlugin

        # Create and start the plugin
        plugin = FreecadMCPPlugin(
            host="localhost",
            port=9876,  # JSON-RPC socket port
            xmlrpc_port=9875,  # XML-RPC port (neka-nat compatible)
            enable_xmlrpc=True,
        )
        plugin.start()

        FreeCAD.Console.PrintMessage("MCP Bridge started!\n")
        FreeCAD.Console.PrintMessage("  - XML-RPC: localhost:9875\n")
        FreeCAD.Console.PrintMessage("  - Socket: localhost:9876\n")
        FreeCAD.Console.PrintMessage(
            "\nYou can now connect your MCP client (Claude Code, etc.) to FreeCAD.\n"
        )

    except ImportError as e:
        FreeCAD.Console.PrintError(
            f"Failed to import MCP Bridge module: {e}\n"
            f"Ensure the freecad-mcp project is accessible at: {project_path}\n"
        )
    except Exception as e:
        FreeCAD.Console.PrintError(f"Failed to start MCP Bridge: {e}\n")


if __name__ == "__main__":
    start_mcp_bridge()
}}

==Links== <!--T:24-->

<!--T:25-->
* [https://modelcontextprotocol.io/ Model Context Protocol Specification]
* [https://claude.com/claude-code Claude Code] - AI assistant that works with MCP
* [[Python_scripting_tutorial|Python Scripting Tutorial]] - FreeCAD Python documentation

[[Category:Macros{{#translation:}}]]
[[Category:User Documentation{{#translation:}}]]
