PrefectHQ/fastmcp · error · FileNotFoundError

No server specification or fastmcp.json found

Error message

No server specification or fastmcp.json found

What it means

The fastmcp CLI's load_and_merge_config requires either an explicit server specification argument or a fastmcp.json in the current directory. When neither is found it logs guidance and raises FileNotFoundError, aborting commands like run, inspect, inspector, and worker.

Source

Thrown at fastmcp_slim/fastmcp/utilities/cli.py:64

    Returns:
        Tuple of (MCPServerConfig, resolved_server_spec)
    """
    config = None
    config_path = None

    # Auto-detect fastmcp.json if no server_spec provided
    if server_spec is None:
        config_path = Path("fastmcp.json")
        if not config_path.exists():
            found_config = MCPServerConfig.find_config()
            if found_config:
                config_path = found_config
            else:
                logger.error(
                    "No server specification provided and no fastmcp.json found in current directory.\n"
                    "Please specify a server file or create a fastmcp.json configuration."
                )
                raise FileNotFoundError("No server specification or fastmcp.json found")

        resolved_spec = str(config_path)
        logger.info(f"Using configuration from {config_path}")
    else:
        resolved_spec = server_spec

    # Load config if server_spec is a .json file
    if resolved_spec.endswith(".json"):
        config_path = Path(resolved_spec)
        if config_path.exists():
            try:
                with open(config_path) as f:
                    data = json.load(f)

                # Check if it's an MCPConfig first (has canonical mcpServers key)
                if "mcpServers" in data:
                    # MCPConfig - we don't process these here, just pass through
                    pass

View on GitHub (pinned to 1f02114297)

Solutions

1. Pass the server spec explicitly, e.g. `fastmcp run server.py`
2. Create a fastmcp.json in the current directory
3. cd into the project directory that contains fastmcp.json

Example fix

// before
$ fastmcp run
FileNotFoundError: No server specification or fastmcp.json found

// after
$ fastmcp run server.py

from pathlib import Path
spec = server_arg or ("fastmcp.json" if Path("fastmcp.json").exists() else None)
if spec is None:
    sys.exit("pass a server file or create fastmcp.json")

try:
    cfg = load_and_merge_config(server_spec=spec)
except FileNotFoundError:
    logger.error("No fastmcp.json in %s; pass server path explicitly", Path.cwd())
    sys.exit(2)

When it happens

Trigger: Running `fastmcp run` / `fastmcp inspect` etc. without a server argument from a directory that contains no fastmcp.json.

Common situations: Running the CLI from the wrong working directory; forgetting to create fastmcp.json; misspelling the server file path so it isn't recognized as a spec.

Related errors

• mcp_tool() got unexpected keyword argument(s): {sorted(unkno
• mcp_resource() got unexpected keyword argument(s): {sorted(u
• mcp_prompt() got unexpected keyword argument(s): {sorted(unk
• {name!r} moved to the fastmcp-tasks package. Install it with
• module {__name__!r} has no attribute {name!r}

AI-assisted analysis of PrefectHQ/fastmcp@1f02114297 (2026-08-29). Data as JSON: /api/errors/3f43d5a374cf79a0. Report an issue: GitHub.