Server crashes with `ModuleNotFoundError: No module named 'mcp'` when optional `fastmcp` dependency is not installed

[unlikeneptunev]

The server fails to start when the optional fastmcp dependency is not installed. The MCP feature routes are imported unconditionally in multiple locations without a guard for ModuleNotFoundError, even though fastmcp is marked as an optional dependency in packaging metadata (confirmed on the Arch Linux AUR package, where fastmcp is listed under Optional Deps, not Depends On).

This differs from the handling of the AI Copilot feature in the same codebase, where the missing langchain_core dependency is caught and logged as a warning, allowing the server to continue running with that feature disabled. The MCP feature does not follow the same pattern.

To Reproduce

1. Install gns3-server 3.1.0a3 without the optional fastmcp / mcp package installed.
2. Run gns3server from the terminal.
3. Server starts initializing, passes initial config and database migration steps, then crashes during the FastAPI lifespan startup phase.

Expected behavior

The server should start successfully with MCP routes disabled and log a warning, consistent with how the AI Copilot feature degrades gracefully.

Error output

First failure point, at import time in gns3server/api/server.py:

File "/usr/lib/python3.14/site-packages/gns3server/api/server.py", line 48, in <module>
    from gns3server.api.routes import mcp
  File "/usr/lib/python3.14/site-packages/gns3server/api/routes/mcp/__init__.py", line 42, in <module>
    from mcp.server.fastmcp import FastMCP
ModuleNotFoundError: No module named 'mcp'

After patching the import in server.py (wrapping in try/except and guarding the two usages at router registration and Starlette route registration), a second unguarded import surfaces at runtime in gns3server/core/tasks.py, inside the startup() lifespan function:

File "/usr/lib/python3.14/site-packages/gns3server/core/tasks.py", line 88, in startup
    from gns3server.api.routes.mcp import set_mcp_server_ready
  File "/usr/lib/python3.14/site-packages/gns3server/api/routes/mcp/__init__.py", line 42, in <module>
    from mcp.server.fastmcp import FastMCP
ModuleNotFoundError: No module named 'mcp'

Environment

• GNS3 server version: 3.1.0a3
• OS: CachyOS (Arch-based), installed via AUR (with paru) package gns3-server
• Python: 3.14.6

Workaround

Manually wrapping all four unguarded references to the mcp module (one import and one router registration in server.py, one import and one function call in tasks.py) in try/except ModuleNotFoundError blocks allows the server to start normally with MCP routes disabled. Happy to share the exact patch if useful.

Suggested fix

Apply the same graceful-degradation pattern already used for the AI Copilot dependency check to the MCP feature imports, in both gns3server/api/server.py and gns3server/core/tasks.py.

[yueguobin]

Thank you for your feedback.

The AI Copilot module is an optional feature, which is why it includes a fallback/graceful degradation mechanism. On the other hand, the MCP interface is a fully integrated module, so no degradation handling was implemented.

In the latest 3.1 branch, the MCP module has been expanded to support 82 tools. As a new feature of the gns3server API, its goal is to simplify the out-of-the-box integration with AI agents like Claude Code.

Should we make the MCP interface an optional installation, similar to the AI Copilot module? For example, something like pip install -e gns3server[mcp]? @grossmj

[unlikeneptunev]

Yes, I personally think making MCP an optional installation (similar to [ai-copilot]) makes sense, especially given how it's being used. My use case is purely local networking labs (OSPF, VLAN topologies in Packet Tracer/GNS3), with no need for AI agent integration at all. A full server crash at startup for a feature I'm not using is a much bigger problem than the feature simply being unavailable.

One thing worth flagging, though, making it an installable extra (e.g. gns3-server[mcp]) alone won't fully solve this unless the import points are also wrapped in graceful degradation, similar to the AI Copilot pattern. I found two separate unguarded import sites that both crash the server when mcp is missing, one at module import time in gns3server/api/server.py (line 48, plus the two usages at router/route registration), and a second one that only surfaces later during the FastAPI lifespan startup() function in gns3server/core/tasks.py (line 88). If only the packaging side is changed without guarding both of these, anyone who installs without the [mcp] extra will still hit the same crash.

I've already patched both locations locally with try/except ModuleNotFoundError guards and confirmed the server starts and runs normally with MCP disabled. Happy to share the diff or test a PR if that's useful.

[grossmj]

Should we make the MCP interface an optional installation, similar to the AI Copilot module? For example, something like pip install -e gns3server[mcp]? @grossmj

Should we make a broader optional dependency like gns3server[ai-support] with the copilot + mcp interface included? Or is there a use case to install then separately (I want one but not the other)?

[yueguobin]

Ah, I see. But why would the AUR package mark mcp/fastmcp as optional anyway? I have already included fastmcp as a requirement in gns3server's requirements.txt.

I'm not entirely familiar with how Arch packages AUR items.

[cristian-ciobanu]

ArchLinux AUR packages ușe a PKGBUILD file to create packages ready for installation.
This is the current PKGBUILD for the GNS3 server 3.1.0 Alpha 3 release. I see the fastmcp package added to the optional dependencies list.
https://aur.archlinux.org/cgit/aur.git/tree/PKGBUILD?h=gns3-server

[yueguobin]

Later, we will make gns3-copilot and mcp optional extension modules. Users can install them via pip install gns3server[ai-support]. If they don't install it, the server will just skip the AI features.