PrefectHQ/fastmcp · error · ImportError

The `anthropic` package is not installed. Install it with `p

Error message

The `anthropic` package is not installed. Install it with `pip install 'fastmcp-slim[anthropic]'` or add `anthropic` to your dependencies.

What it means

ImportError raised at module import of the Anthropic sampling handler when the `anthropic` package is absent. The optional integration is guarded so FastMCP itself works without the SDK, failing fast with an actionable install hint instead of a cryptic ModuleNotFoundError.

Source

Thrown at fastmcp_slim/fastmcp/client/sampling/handlers/anthropic.py:42

    from anthropic import AsyncAnthropic
    from anthropic.types import (
        Base64ImageSourceParam,
        ImageBlockParam,
        Message,
        MessageParam,
        TextBlock,
        TextBlockParam,
        ToolParam,
        ToolResultBlockParam,
        ToolUseBlock,
        ToolUseBlockParam,
    )
    from anthropic.types.model_param import ModelParam
    from anthropic.types.tool_choice_any_param import ToolChoiceAnyParam
    from anthropic.types.tool_choice_auto_param import ToolChoiceAutoParam
    from anthropic.types.tool_choice_param import ToolChoiceParam
except ImportError as e:
    raise ImportError(
        "The `anthropic` package is not installed. "
        "Install it with `pip install 'fastmcp-slim[anthropic]'` or add `anthropic` to your dependencies."
    ) from e

__all__ = ["AnthropicSamplingHandler"]

# Anthropic supports these image MIME types
_ANTHROPIC_IMAGE_MEDIA_TYPES = frozenset(
    {"image/jpeg", "image/png", "image/gif", "image/webp"}
)


def _image_content_to_anthropic_block(content: ImageContent) -> ImageBlockParam:
    """Convert MCP ImageContent to Anthropic ImageBlockParam."""
    if content.mime_type not in _ANTHROPIC_IMAGE_MEDIA_TYPES:
        raise ValueError(
            f"Unsupported image MIME type for Anthropic: {content.mime_type!r}. "
            f"Supported types: {', '.join(sorted(_ANTHROPIC_IMAGE_MEDIA_TYPES))}"

View on GitHub (pinned to 1f02114297)

Solutions

Install the extra: `pip install 'fastmcp-slim[anthropic]'`
Or `pip install anthropic` / add `anthropic` to your dependency manifest
If using uv: `uv add anthropic` or `uv sync --extra anthropic`
Verify with `python -c "import anthropic"` after install

Example fix

// before
pip install fastmcp-slim
from fastmcp.client.sampling.handlers.anthropic import AnthropicSamplingHandler  # ImportError

// after
pip install 'fastmcp-slim[anthropic]'
from fastmcp.client.sampling.handlers.anthropic import AnthropicSamplingHandler  # ok

Defensive patterns

Strategy: fallback

Validate before calling

try:
    import anthropic  # noqa: F401
    ANTHROPIC_AVAILABLE = True
except ImportError:
    ANTHROPIC_AVAILABLE = False

Try / catch

try:
    from fastmcp.client.sampling.handlers.anthropic import AnthropicSamplingHandler
except ImportError:
    AnthropicSamplingHandler = None

handler = AnthropicSamplingHandler(...) if AnthropicSamplingHandler else DefaultFallbackHandler()

Prevention

Install optional extras: pip install 'fastmcp-slim[anthropic]'
Pin the extra in your dependency manifest (pyproject/requirements)
Guard imports of optional handlers in shared library code
Smoke-test imports in CI for every deployment environment

When it happens

Trigger: Importing `fastmcp.client.sampling.handlers.anthropic` or using `AnthropicSamplingHandler` without `anthropic` installed in the environment.

Common situations: Deployed environment missing optional extras; installed `fastmcp-slim` base package without `[anthropic]`; a fresh container/venv that didn't replicate dev dependencies.

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 libraries.

Related errors

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