datawhalechina/hello-agents · error · ImportError

创建内置 MCP 服务器需要 fastmcp 库。请安装: pip install fastmcp

Error message

创建内置 MCP 服务器需要 fastmcp 库。请安装: pip install fastmcp

What it means

An ImportError raised by the built-in MCP server factory in protocol_tools.py when 'import fastmcp' (or the FastMCP symbol) fails. The code builds a demonstration MCP server with six tools (add through get_system_info) inside a try block; if the fastmcp distribution is absent or broken, the except ImportError re-raises with an install hint. This is a dependency-availability error, not a logic error.

Source

Thrown at Co-creation-projects/AstrumPush-Smart-Recipe-Agent/protocol_tools.py:252

                """友好问候"""
                return f"Hello, {name}! 欢迎使用 HelloAgents MCP 工具！"

            @server.tool()
            def get_system_info() -> dict:
                """获取系统信息"""
                import platform
                import sys
                return {
                    "platform": platform.system(),
                    "python_version": sys.version,
                    "server_name": "HelloAgents-BuiltinServer",
                    "tools_count": 6
                }

            return server

        except ImportError:
            raise ImportError(
                "创建内置 MCP 服务器需要 fastmcp 库。请安装: pip install fastmcp"
            )

    def _discover_tools(self):
        """发现MCP服务器提供的所有工具"""
        try:
            from hello_agents.protocols.mcp.client import MCPClient
            import asyncio

            async def discover():
                client_source = self.server if self.server else self.server_command
                async with MCPClient(client_source, self.server_args, env=self.env) as client:
                    tools = await client.list_tools()
                    return tools

            # 运行异步发现
            try:
                loop = asyncio.get_running_loop()

View on GitHub (pinned to 606a07d341)

Solutions

1. Run 'pip install fastmcp' in the same virtualenv/interpreter the agent runs under (verify with 'which python' / 'pip -V')
2. Pin it in requirements.txt or pyproject dependencies if the builtin server is used in deployment
3. If installation fails, check Python version compatibility with fastmcp's supported range
4. Alternatively pass server_command to use an external MCP server via stdio, avoiding the in-process fastmcp dependency

Example fix

# before
try:
    from fastmcp import FastMCP
except ImportError:
    raise ImportError("创建内置 MCP 服务器需要 fastmcp 库。请安装: pip install fastmcp")

# after (shell)
# pip install fastmcp
# python -c "import fastmcp; print(fastmcp.__version__)"  # sanity check

import importlib.util
if importlib.util.find_spec('fastmcp') is None:
    raise SystemExit('fastmcp missing — run: pip install fastmcp')
# or in a shell: python -c "import fastmcp" || pip install fastmcp

def fastmcp_available() -> bool:
    import importlib.util
    return importlib.util.find_spec('fastmcp') is not None

try:
    server = build_builtin_server()
except ImportError as e:
    if 'fastmcp' in str(e):
        subprocess.check_call([sys.executable, '-m', 'pip', 'install', 'fastmcp'])
        server = build_builtin_server()  # retry once after install
    else:
        raise

When it happens

Trigger: Instantiating the builtin MCP server component (which calls the factory returning 'server') in an environment where fastmcp is not installed, is installed under an incompatible Python version, or the package is corrupted so import raises ImportError. Installing via the suggested 'pip install fastmcp' into the active interpreter resolves it.

Common situations: Fresh environment where only hello_agents core was installed without the MCP extras; using a different virtualenv/conda env than the one where fastmcp was pip-installed; Python version mismatch yielding an unusable wheel; requirements.txt missing the optional dependency in deployment images.

Related errors

• 创建内置 MCP 服务器需要 fastmcp 库。请安装: pip install fastmcp
• 除数不能为零
• 请安装 hello-agents: pip install 'hello-agents[all]>=0.2.7'
• 除数不能为零
• 无法导入 {module_name}.{class_name or ''}: {e}

AI-assisted analysis of datawhalechina/hello-agents@606a07d341 (2026-08-14). Data as JSON: /api/errors/fc39e5b87bad058c. Report an issue: GitHub.