ContextQMD
Back to Fastmcp

Icons

docs/servers/icons.mdx

4.0.0a15.6 KB
Original Source

import { VersionBadge } from '/snippets/version-badge.mdx'

<VersionBadge version="2.13.0" />

Icons provide visual representations for your MCP servers and components, helping client applications present better user interfaces. When displayed in MCP clients, icons help users quickly identify and navigate your server's capabilities.

Icon Format

Icons use the standard MCP Icon type from the MCP protocol specification. Each icon specifies a source URL or data URI, and optionally includes MIME type, size, and theme information.

python
from mcp_types import Icon

icon = Icon(
    src="https://example.com/icon.png",
    mime_type="image/png",
    sizes=["48x48"]
)

The fields serve different purposes:

  • src: URL or data URI pointing to the icon image
  • mime_type (optional): MIME type of the image (e.g., "image/png", "image/svg+xml")
  • sizes (optional): Array of size descriptors (e.g., ["48x48"], ["any"])
  • theme (optional): The UI theme the icon is designed for, "light" or "dark"

Server Icons

Add icons and a website URL to your server for display in client applications. Multiple icons at different sizes help clients choose the best resolution for their display context.

python
from fastmcp import FastMCP
from mcp_types import Icon

mcp = FastMCP(
    name="WeatherService",
    website_url="https://weather.example.com",
    icons=[
        Icon(
            src="https://weather.example.com/icon-48.png",
            mime_type="image/png",
            sizes=["48x48"]
        ),
        Icon(
            src="https://weather.example.com/icon-96.png",
            mime_type="image/png",
            sizes=["96x96"]
        ),
    ]
)

Server icons appear in MCP client interfaces to help users identify your server among others they may have installed.

Component Icons

Icons can be added to individual tools, resources, resource templates, and prompts. This helps users visually distinguish between different component types and purposes.

Tool Icons

python
from mcp_types import Icon

@mcp.tool(
    icons=[Icon(src="https://example.com/calculator-icon.png")]
)
def calculate_sum(a: int, b: int) -> int:
    """Add two numbers together."""
    return a + b

Resource Icons

python
@mcp.resource(
    "config://settings",
    icons=[Icon(src="https://example.com/config-icon.png")]
)
def get_settings() -> dict:
    """Retrieve application settings."""
    return {"theme": "dark", "language": "en"}

Resource Template Icons

python
@mcp.resource(
    "user://{user_id}/profile",
    icons=[Icon(src="https://example.com/user-icon.png")]
)
def get_user_profile(user_id: str) -> dict:
    """Get a user's profile."""
    return {"id": user_id, "name": f"User {user_id}"}

Prompt Icons

python
@mcp.prompt(
    icons=[Icon(src="https://example.com/prompt-icon.png")]
)
def analyze_code(code: str):
    """Create a prompt for code analysis."""
    return f"Please analyze this code:\n\n{code}"

Theme Variants

<VersionBadge version="4.0.0" />

MCP clients like VS Code and GitHub Desktop render their own interface in either a light or dark theme, and an icon designed for one can be hard to see against the other, such as a dark logo that disappears into a dark sidebar. The theme field on Icon tells a client which UI theme an icon is designed for, so the client can display the version that stays visible.

Supply two icons with complementary theme values and the client picks the one that matches its current appearance:

python
from fastmcp import FastMCP
from mcp_types import Icon

mcp = FastMCP(
    name="WeatherService",
    icons=[
        Icon(src="https://weather.example.com/icon-light.png", theme="light"),
        Icon(src="https://weather.example.com/icon-dark.png", theme="dark"),
    ],
)

The same field works on tools, resources, resource templates, and prompts:

python
from mcp_types import Icon

@mcp.tool(
    icons=[
        Icon(src="https://example.com/calculator-light.png", theme="light"),
        Icon(src="https://example.com/calculator-dark.png", theme="dark"),
    ]
)
def calculate_sum(a: int, b: int) -> int:
    """Add two numbers together."""
    return a + b

Omitting theme means the icon is assumed suitable for any theme. That's the right choice for a single icon with enough contrast to read clearly against both light and dark backgrounds.

Using Data URIs

For small icons or when you want to embed the icon directly without external dependencies, use data URIs. This approach eliminates the need for hosting and ensures the icon is always available.

python
from mcp_types import Icon
from fastmcp.utilities.types import Image

# SVG icon as data URI
svg_icon = Icon(
    src="data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCI+PHBhdGggZD0iTTEyIDJDNi40OCAyIDIgNi40OCAyIDEyczQuNDggMTAgMTAgMTAgMTAtNC40OCAxMC0xMFMxNy41MiAyIDEyIDJ6Ii8+PC9zdmc+",
    mime_type="image/svg+xml"
)

@mcp.tool(icons=[svg_icon])
def my_tool() -> str:
    """A tool with an embedded SVG icon."""
    return "result"

Generating Data URIs from Files

FastMCP provides the Image utility class to convert local image files into data URIs.

python
from mcp_types import Icon
from fastmcp.utilities.types import Image

# Generate a data URI from a local image file
img = Image(path="./assets/brand/favicon.png")
icon = Icon(src=img.to_data_uri())

@mcp.tool(icons=[icon])
def file_icon_tool() -> str:
    """A tool with an icon generated from a local file."""
    return "result"

This approach is useful when you have local image assets and want to embed them directly in your server definition.