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.

Tools

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.

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.