Skip to main content
Glama

pyside-iconify-mcp

Help your AI assistant write correct pyside-iconify code.

English | 中文 | 日本語 | 한국어 | Español | Français | Deutsch | Русский | Português (BR)

An MCP server for pyside-iconify. It lets an AI assistant look up real icons, read the library's exact usage, and check the code it wrote, instead of guessing.

This project is not affiliated with the Iconify project.

Why

AI assistants often get pyside-iconify code wrong in ways that only show up at run time:

  • they invent icon names that do not exist (mdi:home-filled)

  • they use parameter names that do not exist, or that belong to a different entry point (get_icon(..., hover_color=...))

  • they pass a single color to a multi-color icon and expect it to change

  • they pick get_icon when they need an animated icon

This server lets the assistant look things up and check its work instead of guessing.

Related MCP server: unreal-python-mcp

Tools

Tool

What it does

Needs network

search_icons

Find real icons by keyword, using the official Iconify search API

yes

check_icons

Check that icon names exist; report whether each is multi-color or animated; suggest similar icons for missing ones

yes

get_reference

Return the exact, version-matched usage of the library by topic

no

check_code

Check the pyside-iconify calls in a piece of Python code, without running it

optional

All four are read-only. The server never touches your project files and never runs your code. The only network access is to the public Iconify API (https://api.iconify.design); results are cached in memory for an hour.

search_icons

Input: query (keywords; several words must all match), optional prefix (an icon set such as mdi), optional limit (1 to 100, default 20).

Output: status (ok or unavailable), icons (a list of prefix:name), collections (name, license and size of the icon sets involved). unavailable means the lookup failed, for example without network; it does not mean nothing exists.

check_icons

Input: names, a list of 1 to 50 icon names.

Output: one entry per name.

status

Meaning

ok

The icon exists. Also reports monotone, fixed_colors, animated and notes

not_found

The icon (or its icon set) does not exist. Includes suggestions

invalid_name

Not of the form prefix:name

unavailable

The check failed (for example no network). Says nothing about whether it exists

The monotone, color and animation results are computed by pyside-iconify itself, so they match what the library does at run time.

get_reference

Input: optional topic. Without a topic it lists them: overview, icon_widget, get_icon, set_icon, colors, sizes, animation, pitfalls, runtime.

Output: Markdown. The signatures are generated from the installed pyside-iconify, so they always match its version; explanations and examples are written by hand and tested against the library.

check_code

Input: code (Python source), optional verify_icon_names (default true).

Output: ok (true when there are no errors), issues (line, column, severity, code, message, suggestion), skipped (what could not be checked), checked (counts).

It looks for:

  • imports of names or modules that do not exist

  • unknown parameters, parameters used on the wrong entry point, missing or duplicated arguments

  • invalid values: size, colors, opacity, rotate, animation, periods, speed

  • conflicting options (spin=True with another animation, animation_depth with spin)

  • malformed icon names, and icon names that do not exist

  • a single color on a multi-color icon, and animated icons used with get_icon

What it promises: when it returns ok: true, the usage it could read directly from the code (parameter names, literal values, literal icon names) is correct. What it cannot know is listed under skipped instead of being guessed: values that come from variables or function calls, *args / **kwargs, and anything that only goes wrong at run time (no QApplication, widgets created off the main thread). It never reports an error it is not sure about.

Setup

Add it to your AI client as a stdio server that runs uvx pyside-iconify-mcp.

Claude Code

claude mcp add --transport stdio pyside-iconify -- uvx pyside-iconify-mcp

Add --scope project to store it in the project's .mcp.json and share it with your team. See the Claude Code documentation.

ChatGPT and Codex

The ChatGPT desktop app, the Codex CLI and the Codex IDE extension share one MCP configuration.

codex mcp add pyside-iconify -- uvx pyside-iconify-mcp

Or add this to ~/.codex/config.toml:

[mcp_servers.pyside-iconify]
command = "uvx"
args = ["pyside-iconify-mcp"]

See the Codex documentation.

Cursor

Create .cursor/mcp.json in your project, or ~/.cursor/mcp.json to use it in every project:

{
    "mcpServers": {
        "pyside-iconify": {
            "type": "stdio",
            "command": "uvx",
            "args": ["pyside-iconify-mcp"]
        }
    }
}

See the Cursor documentation.

OpenCode

Add it to your opencode.json. Here command is a single array that includes the arguments:

{
    "$schema": "https://opencode.ai/config.json",
    "mcp": {
        "pyside-iconify": {
            "type": "local",
            "command": ["uvx", "pyside-iconify-mcp"],
            "enabled": true
        }
    }
}

See the OpenCode documentation.

VS Code

Create .vscode/mcp.json in your project. VS Code uses servers as the top-level key, not mcpServers:

{
    "servers": {
        "pyside-iconify": {
            "type": "stdio",
            "command": "uvx",
            "args": ["pyside-iconify-mcp"]
        }
    }
}

You can also run MCP: Add Server from the Command Palette, choose Command (stdio) and enter uvx pyside-iconify-mcp. See the VS Code documentation.

WorkBuddy

Create or edit ~/.workbuddy/mcp.json (the file name has no leading dot):

{
    "mcpServers": {
        "pyside-iconify": {
            "command": "uvx",
            "args": ["pyside-iconify-mcp"]
        }
    }
}

A new server is not enabled automatically: open the custom connectors entry at the top right of the connector management page and click Trust on it.

CodeBuddy

The command below is for the CodeBuddy CLI:

codebuddy mcp add --scope user pyside-iconify -- uvx pyside-iconify-mcp

Use --scope project to store it in the project's .mcp.json instead. See the CodeBuddy documentation.

TRAE

Open Settings, then MCP, choose Add, then Create Manually, and paste:

{
    "mcpServers": {
        "pyside-iconify": {
            "command": "uvx",
            "args": ["pyside-iconify-mcp"]
        }
    }
}

For a single project, turn on Enable Project MCP on the same page and put the same JSON in .trae/mcp.json. See the TRAE documentation.

Other clients

Clients that use an mcpServers JSON config:

{
    "mcpServers": {
        "pyside-iconify": {
            "command": "uvx",
            "args": ["pyside-iconify-mcp"]
        }
    }
}

The exact config file and key names differ between clients; check your client's documentation for how to add a local (stdio) MCP server.

Run from a checkout

{
    "mcpServers": {
        "pyside-iconify": {
            "command": "uv",
            "args": [
                "run",
                "--directory",
                "/path/to/pyside-iconify-mcp",
                "pyside-iconify-mcp"
            ]
        }
    }
}

If your client cannot start uv, point it at the program installed in the project's virtual environment instead (create it first with uv sync): .venv/Scripts/pyside-iconify-mcp.exe on Windows, .venv/bin/pyside-iconify-mcp on macOS and Linux.

{
    "mcpServers": {
        "pyside-iconify": {
            "command": "/path/to/pyside-iconify-mcp/.venv/Scripts/pyside-iconify-mcp.exe"
        }
    }
}

Requirements

Python 3.10 to 3.14. The server depends on pyside-iconify (without any Qt extra, so Qt is not installed) and on FastMCP 4.1.x. The version of pyside-iconify it was built against is pinned to a minor range; a newer minor version of the library needs a matching release of this server.

Development

Requires uv.

uv sync --group test
uv run pytest -v
uv run pyside-iconify-mcp

The tests do not use the network. Every tool lives in its own file under src/pyside_iconify_mcp/tools/, named after the tool; shared code is in common/. See docs/architecture.md for the layout and how to add a tool.

License

MIT. Icon collections are subject to their own licenses.

Available Tools

4 tools
check_codeCheck CodeA
Read-onlyIdempotent

Check the pyside-iconify usage in a piece of Python code without running it. Finds unknown imports, unknown or misplaced parameters (for example hover_color on get_icon), invalid values (size, color, opacity, rotate, animation), conflicting options, malformed or non-existent icon names, and multi-color or animated icons used in ways that do not work. 'ok' is true when there are no errors. Only values written literally in the code are checked; anything else is listed under 'skipped' instead of being guessed. Run it on finished code and fix every error.

Inputs: code (required), verify_icon_names. Returns: object

check_iconsCheck IconsA
Read-onlyIdempotent

Verify icon names before using them in code. For each name returns whether it exists (status 'ok', 'not_found', 'invalid_name' or 'unavailable'), and for existing icons whether they are monotone or multi-color (fixed_colors), whether they animate themselves, and notes about what that means for color and animation arguments. For missing icons returns similar real icons. 'unavailable' means the check failed (for example no network), not that the icon is missing.

Inputs: names (required). Returns: object

get_referenceGet ReferenceA
Read-onlyIdempotent

Read the authoritative, version-matched usage of pyside-iconify: exact signatures, accepted values, working examples and a table of common mistakes. Call it before writing pyside-iconify code; start with topic 'overview'. Call without a topic to list the topics.

Inputs: topic. Returns: result

search_iconsSearch IconsA
Read-onlyIdempotent

Find real icons by keyword (use this instead of guessing an icon name). Returns 'prefix:name' strings that exist in Iconify, plus the icon sets they belong to. A query with several words must match all of them; narrow with 'prefix' (e.g. 'mdi', 'lucide'). status 'unavailable' means the lookup failed (for example no network), not that nothing exists.

Inputs: query (required), limit, prefix. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool has a clearly distinct role: documentation lookup, icon discovery, icon-name validation, and static code checking. Although search_icons and check_icons both involve icon names, their descriptions make the distinction explicit: one finds icons, the other verifies them before use.

    Naming Consistency5/5

    All tool names use consistent snake_case with a verb_noun pattern: get_reference, search_icons, check_icons, check_code. The convention is predictable throughout.

    Tool Count5/5

    Four tools is well-scoped for a focused pyside-iconify assistance server. Each tool covers a necessary part of the workflow without redundant operations.

    Completeness5/5

    The surface covers the full assistance lifecycle: reference documentation, icon discovery, icon validation, and code validation. There are no obvious dead ends for an agent writing pyside-iconify code.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers