tech-icons

English | 中文

5,200+ Cloud Tech Icons (SVG+PNG) · Searchable MCP Server · Architecture Diagrams

The missing icon layer for AI-assisted architecture diagramming. Give your LLMs the power to see and place cloud icons across AWS, Azure, GCP, Kubernetes, on-prem infrastructure, and 20+ other vendors — directly, without switching tabs or hunting through vendor docs.

✨ Features

🔍 Multi-Tier Search — Exact ID → Keyword → Fuzzy → Semantic embedding search, layered for precision and recall
🎨 Dual Format Support — SVG and PNG icons across 21 vendors. Parameterized: image_type="svg" (default) or image_type="png", with automatic fallback
🔗 Cross-Vendor Concepts — compare_icons("kubernetes") returns the K8s icon from AWS, Azure, GCP, and Kubernetes vendor in one call
🌐 Streamable HTTP + stdio — Run locally (stdio) or as a web service (--transport http), or both (--transport dual)
🖥️ Built-in Web UI — --web launches a local icon browser (FastAPI + SPA) for visual exploration
📦 Zero Build, Works Everywhere — Icons are bundled in the wheel; no local build step, works with uvx directly
⚡ FastMCP Framework — Modern decorator-based tool registration with automatic JSON Schema generation
🧩 Extensible — format="ppt_master" generates placeholders for ppt-master; format="inline_group" composes directly into SVG architecture diagrams

📋 Table of Contents

tech-icons

🚀 Quick Start

Run directly (no install needed)

# stdio MCP server — ready for Claude Desktop, Cursor, etc.
uvx tech-icons

# With semantic search (sentence-transformers embeddings)
uvx --with 'tech-icons[semantic]' tech-icons

# Launch the web icon browser
uvx --with 'tech-icons[web]' tech-icons --web --open

# Run as a Streamable HTTP service
uvx --with 'tech-icons[web]' tech-icons --transport http --port 8000

Run from this repository (development)

git clone https://github.com/zhiweio/tech-icons.git
cd tech-icons
uv run tech-icons

That's it. The published wheel bundles the full icon catalog (~1.4 MB metadata + SVGs)—no local build step, no asset download.

📦 Installation & Requirements

Requirement	Details
Python	≥ 3.10
Package Manager	uv (recommended), pip, pipx
Core Dependencies	`fastmcp`, `pyyaml`, `rapidfuzz`
Web UI (optional)	`fastapi`, `uvicorn` (`[web]` extra)
Semantic Search (optional)	`sentence-transformers`, `numpy` (`[semantic]` extra)
Everything	`[all]` extra = `[web,semantic]`

# Install with all features
uvx --with 'tech-icons[all]' tech-icons

# Or install globally
uv tool install 'tech-icons[all]'
tech-icons --web

Extras at a glance

Extra	Adds	When to use
none	Core MCP server (stdio)	Claude Desktop, Cursor, any MCP client
`[web]`	FastAPI + uvicorn	`--web` browser UI, `--transport http`
`[semantic]`	sentence-transformers	Tier-4 semantic search for vague queries
`[all]`	both of the above	Full functionality

🔧 Usage Modes

tech-icons supports five distinct operating modes, selected by CLI flags:

tech-icons                                    # stdio MCP (default)
tech-icons --transport http --port 8000       # Streamable HTTP MCP
tech-icons --transport dual                   # stdio + HTTP simultaneously
tech-icons --web --open                       # Local browser UI
tech-icons --ppt-master aws --target ./icons/  # Bulk icon export

1. MCP Server (stdio)

The default mode. The server reads MCP JSON-RPC messages from stdin and writes responses to stdout. This is what MCP clients like Claude Desktop and Cursor expect.

uvx tech-icons
# or with semantic search:
uvx --with 'tech-icons[semantic]' tech-icons

How it works: The client process spawns uvx tech-icons as a child process, communicates via stdin/stdout. One process per client session. No ports, no network—pure local IPC.

2. MCP Server (Streamable HTTP)

Run as a persistent HTTP service. Multiple clients can connect simultaneously. Uses the Streamable HTTP protocol for full bidirectional communication including streaming responses.

uvx --with 'tech-icons[web]' tech-icons --transport http --host 0.0.0.0 --port 8000

How it works: Uvicorn ASGI server starts, serving the MCP endpoint at http://host:port/mcp. Clients connect over HTTP/2 with streaming support. The server stays running—start once, many clients connect.

3. Dual Transport (stdio + HTTP)

Run both transports simultaneously on a single process with a shared engine instance. Perfect for development workflows where you want local IDE integration and a network-accessible service.

uvx --with 'tech-icons[web]' tech-icons --transport dual --port 8000

How it works: asyncio.gather() runs run_stdio_async() and run_http_async() concurrently. Both share the same SearchEngine instance (loaded once). Use Ctrl+C to stop.

4. Web UI

Launch a local icon browser with full-text search, vendor/category filters, paginated catalog, and SVG preview/download.

uvx --with 'tech-icons[web]' tech-icons --web --port 8765 --open

Opens http://127.0.0.1:8765 in your browser. The web UI uses the same SearchEngine class as the MCP server—no logic duplication.

5. PPT-Master Export

Batch-export SVG icons into a ppt-master template directory. Supports vendor names, comma-separated icon IDs, or all.

# Export a single vendor
uvx tech-icons --ppt-master aws --target ./templates/icons/

# Export specific icons
uvx tech-icons --ppt-master aws/compute/lambda,gcp/compute/cloud-run

# Export everything
uvx tech-icons --ppt-master all

# Use symlinks (no file copy overhead)
uvx tech-icons --ppt-master aws --symlink

🖥️ MCP Client Configuration

Claude Desktop / Claude Code

{
  "mcpServers": {
    "tech-icons": {
      "command": "uvx",
      "args": ["tech-icons"]
    }
  }
}

With semantic search

{
  "mcpServers": {
    "tech-icons": {
      "command": "uvx",
      "args": ["--with", "tech-icons[semantic]", "tech-icons"]
    }
  }
}

Streamable HTTP (remote / self-hosted)

{
  "mcpServers": {
    "tech-icons": {
      "url": "http://your-server:8000/mcp",
      "transport": "http"
    }
  }
}

Cursor / Windsurf / other MCP-compatible editors

Use the same stdio configuration as Claude Desktop above. For HTTP transport, check your editor's MCP documentation for HTTP endpoint support.

🐳 Docker

Pre-built Docker image with both MCP server and Web UI modes. Choose via the SERVER_MODE environment variable.

Quick Start

# Build the image
docker build -t tech-icons .

# Run as MCP Streamable HTTP server (default)
docker run -p 8765:8765 tech-icons

# Run as Web UI (icon browser)
docker run -p 8765:8765 -e SERVER_MODE=web tech-icons

docker-compose

# MCP server mode
docker compose --profile mcp up -d

# Web UI mode
docker compose --profile web up -d

Environment Variables

Variable	Default	Description
`SERVER_MODE`	`http`	`http` = MCP Streamable HTTP server, `web` = FastAPI web UI
`HOST`	`0.0.0.0`	Bind address (always `0.0.0.0` inside the container)
`PORT`	`8765`	Listen port
`LOG_LEVEL`	`info`	Python log level

Claude Desktop Configuration (Docker)

Connect Claude Desktop to a containerized tech-icons via Streamable HTTP:

{
  "mcpServers": {
    "tech-icons": {
      "type": "streamableHttp",
      "url": "http://localhost:8765/mcp"
    }
  }
}

Note: The container binds 0.0.0.0:8765. If running the container on a remote host, replace localhost with the host's IP address.

🛠️ Tools & API Reference

tech-icons exposes 7 tools, 1 resource, and cross-vendor concept groups:

Tools

Tool	Parameters	Returns	Description
`search_icons`	`query` (required), `vendor`, `category`, `limit`	`list[dict]`	Multi-tier search: exact ID → keyword → fuzzy → semantic
`get_icon`	`id` (e.g., `aws/compute/lambda`)	`dict`	Full metadata: vendor, category, name, aliases, tags, description, path
`get_icon_image`	`id`, `format` (default: `raw`), `image_type` (default: `svg`)	`str` or `list`	Icon content in chosen format and image type (SVG or PNG); `download` returns `Image` attachment
`list_categories`	`vendor` (optional)	`list[str]`	All icon categories, optionally filtered by vendor
`list_vendors`	none	`dict[str, int]`	Vendor name → icon count mapping (21 vendors)
`list_concepts`	none	`list[str]`	Cross-vendor concept names (e.g., `kubernetes`, `serverless`)
`compare_icons`	`concept` (e.g., `kubernetes`)	`dict`	Icons from all vendors for a concept, grouped by vendor

All parameters with Annotated[type, "description"] type hints auto-generate JSON Schema via FastMCP.

Resource

URI	MIME Type	Content
`icon://catalog`	`application/json`	Full 5,200+ entry icon catalog with all metadata

LLM Usage Examples

Find an icon for a specific AWS service:

search_icons(query="Lambda")

Compare Kubernetes icons across clouds:

compare_icons(concept="kubernetes")

Get a data URI for embedding in an HTML architecture diagram:

get_icon_image(id="gcp/compute/cloud-run", format="data_uri")

Get a PNG icon for a Kubernetes component:

get_icon_image(id="kubernetes/compute/pod", image_type="png", format="data_uri")

List all Azure database services:

search_icons(query="database", vendor="azure", category="databases")

Explore the full catalog:

read_resource("icon://catalog")

🎨 Format Options

Each format serves a distinct integration scenario:

Format	Output	Use Case	Example
`raw`	SVG XML string	Inspection, direct embedding	`"<svg xmlns=\"...\">...</svg>"`
`path`	Absolute filesystem path	Local tooling, file references	`"/path/to/icons/aws/compute/lambda.svg"`
`base64`	Base64-encoded SVG	Binary transport, JSON payloads	`"PHN2ZyB4bWxucz0i..."`
`data_uri`	`data:image/svg+xml;base64,...`	HTML `<img>` tags, CSS backgrounds	`"data:image/svg+xml;base64,..."`
`inline_group`	`<g viewBox="...">...</g>`	Direct SVG composition in diagrams	`"<g viewBox=\"0 0 64 64\"><path d=\"...\"/></g>"`
`ppt_master`	`<use data-icon="tech-icons/..."/>`	ppt-master skill placeholder	`"<use data-icon=\"tech-icons/aws/compute/lambda\"/>"`
`download`	Text summary + `Image` attachment	Download the SVG file	Text + `Image(data=..., format="svg+xml")`

🏷️ Icon ID Convention

All icons follow a consistent canonical ID format:

{vendor}/{category}/{name}

Examples:

aws/compute/lambda — AWS Lambda
azure/databases/cosmos-db — Azure Cosmos DB
gcp/serverless-computing/cloud-run — Cloud Run
microsoft/365/teams — Microsoft Teams
cncf/orchestration/kubernetes — Kubernetes
devicon/framework/react — React

IDs are lowercase, with hyphens for multi-word names. Use list_categories(vendor="aws") to explore available categories for a vendor.

🏗️ Architecture & Design

Key Design Decisions

Single SearchEngine, multiple interfaces — The SearchEngine class has one instance. The MCP server, FastAPI web app, and ppt-master CLI all wrap it—no logic duplication.
Tiered search with early termination — Search stops at the first tier that returns ≥ limit results. Most queries hit Tier 1 (exact ID) or Tier 2 (keyword index) and never reach fuzzy or semantic—fast and cheap.
Bundled catalog in wheel — icons.json, keyword_index.json, and SVGs are packaged via hatchling. importlib.resources.files() resolves paths at runtime, works in both dev (uv run) and installed (uvx, pipx) environments.
Lazy loading — The engine loads catalog data from disk only on first access (_ensure_loaded()). In stdio mode, engine.load() is called explicitly before mcp.run().
FastMCP decorator pattern — Each tool is a standalone function decorated with @mcp.tool. Python type hints (Annotated[str, "desc"], Literal["aws", ...]) auto-generate JSON Schema. No manual inputSchema writing.
Cross-vendor concept registry — enrichments.yaml defines technology concepts (e.g., "kubernetes") and maps them to icon IDs across vendors. Concept metadata is loaded on engine initialization and available as engine.concepts.

Technology Stack

Component	Technology	Rationale
MCP Framework	FastMCP 3.4	Decorator-based, auto Schema, stdio+HTTP dual transport
Search Engine	Custom (4-tier)	Exact → keyword → fuzzy → semantic, early termination
Fuzzy Matching	rapidfuzz	Token-sort ratio scoring, C-accelerated
Semantic Search	sentence-transformers	all-MiniLM-L6-v2, optional extra
Web UI	FastAPI + SPA	Shared engine instance, CORS-enabled
Build System	hatchling	PEP 517, supports bundling data files
Package Manager	uv	Fast resolver, `uvx` for one-shot runs

🔗 Integrations

ppt-master

The ppt_master format generates <use data-icon="tech-icons/..."/> elements compatible with ppt-master's embed_icons.py hook. Use --ppt-master to bulk-export icons:

uvx tech-icons --ppt-master aws --target ./templates/icons/
uvx tech-icons --ppt-master aws/compute/lambda,gcp/compute/cloud-run --symlink

Architecture Diagrams

Use format="data_uri" for HTML <img> tags, or format="inline_group" for direct SVG <g> element composition:

<!-- data_uri: embed in HTML -->
<img src="DATA_URI_OUTPUT" alt="AWS Lambda" class="tech-icon--md" />

<!-- inline_group: embed in SVG canvas -->
<svg viewBox="0 0 800 400">
  <g transform="translate(50, 50)">
    INLINE_GROUP_OUTPUT
  </g>
</svg>

See docs/integration-arch-diagram.md for complete examples with CSS styling, multi-cloud layouts, and vendor color conventions.

Semantic Search

Add [semantic] extra to enable the 4th search tier. Useful for vague queries ("that thing for serverless") where keyword matching falls short:

uvx --with 'tech-icons[semantic]' tech-icons

🔬 Development

# Clone and set up
git clone https://github.com/zhiweio/tech-icons.git
cd tech-icons
uv sync --group dev

# Run tests
uv run pytest tests/ -v

# Lint + type check
uv run ruff check tech_icons/ tests/
uv run mypy tech_icons/

# Format
uv run ruff format tech_icons/ tests/

# All checks (format + lint + typecheck + test)
make all

Project Structure

tech-icons-abilities/
├── tech_icons/                # Main package
│   ├── server.py              # FastMCP server + CLI (main entry point)
│   ├── search.py              # 4-tier search engine
│   ├── formats.py             # 6 SVG output format adapters
│   ├── concepts.py            # Cross-vendor concept registry
│   ├── normalize.py           # SVG normalization & catalog generation
│   ├── _paths.py              # Runtime path resolution (importlib.resources)
│   ├── web/
│   │   ├── app.py             # FastAPI HTTP API
│   │   └── static/            # SPA frontend (index.html + assets)
│   ├── bridges/
│   │   └── ppt_master.py      # ppt-master icon export bridge
│   ├── catalog/               # Pre-built data files (bundled in wheel)
│   │   ├── icons.json         # 3,140+ entries with full metadata
│   │   ├── keyword_index.json # Inverted keyword index
│   │   ├── embeddings.npz     # Sentence embeddings (optional)
│   │   ├── embedding_ids.json # Embedding-to-ID mapping
│   │   └── enrichments.yaml   # Cross-vendor concept definitions
│   └── icons/                 # Bundled SVG files (~3,140 files)
├── tests/                     # pytest test suite (258+ tests)
├── scripts/
│   ├── build_catalog.py       # Catalog build pipeline
│   └── normalize_icons.py     # SVG normalization script
├── docs/                      # Documentation, screenshots
├── pyproject.toml             # Build config, dependencies, tooling
├── Makefile                   # Development task runner
└── README.md                  # This file

Running Tests

uv run pytest tests/ -v          # All tests
uv run pytest tests/test_server.py -v  # Server-specific
uv run pytest tests/ -v --cov   # With coverage

Tooling

Formatter: ruff (line-length: 120)
Linter: ruff (E, W, F, I, N, UP, B, A, S, T20, RUF)
Type checker: mypy (disallow-untyped-defs)
Test runner: pytest + pytest-asyncio (asyncio_mode=auto)

❓ FAQ

Q: Do I need to build the catalog locally? A: No. icons.json and SVGs are bundled in the wheel. uvx tech-icons works immediately.

Q: How is this different from the AWS/Azure/GCP icon libraries? A: tech-icons aggregates icons from 6 vendors into a single, searchable MCP server with consistent IDs and a cross-vendor concept system. Instead of hunting through multiple icon sets, you ask the LLM and it retrieves the right icon.

Q: Can I use this without an MCP client? A: Yes. Use --web for a browser UI, --transport http for a REST-ish API, or import SearchEngine directly in Python (from tech_icons import SearchEngine).

Q: Does semantic search require GPU? A: No. The default all-MiniLM-L6-v2 model runs on CPU. Embeddings are precomputed—only the query vector is generated at runtime.

Q: Can I add my own icons or vendors? A: Yes. Put SVG files under assets/your-vendor-*, update tech_icons/normalize.py with a collector function, then run scripts/build_catalog.py. See Development above.

Q: What MCP protocol version does this support? A: FastMCP 3.4 supports MCP protocol version 2025-03-26. All transports (stdio, Streamable HTTP) use this protocol.

🏅 Icon Sources & Attributions

tech-icons aggregates icons from the following sources. The project itself (server, search engine, tooling) is MIT-licensed, but the bundled icon files retain their original licenses and terms. Please review each source's license before redistributing or modifying the icons.

Source	Vendor(s)	License / Terms	Notes
AWS Architecture Icons	`aws`	AWS Terms of Service	Free to use for architecture diagrams.
Azure Architecture Icons	`azure`	Microsoft Terms	Free to use for architecture diagrams.
Google Cloud Icons	`gcp`	Google Cloud Brand Guidelines	Free to use for architecture diagrams.
Microsoft 365 Architecture Icons	`microsoft` (365)	Microsoft Terms
Dynamics 365 Icons	`microsoft` (dynamics-365)	Microsoft Terms
Microsoft Entra Architecture Icons	`microsoft` (entra)	Microsoft Terms
Microsoft Fabric Icons	`microsoft` (fabric)	Microsoft Terms
Power Platform Icons	`microsoft` (power-platform)	Microsoft Terms
CNCF Artwork	`cncf`	CNCF Trademark & Logo Guidelines	Trademarks owned by CNCF and respective projects.
Devicon	`devicon`	MIT License	Icon fonts and SVGs for software technologies.
Developer Icons	`developer`	MIT License	Flat, colored technology icons.
mingrammer/diagrams	`alibabacloud`, `digitalocean`, `elastic`, `firebase`, `generic`, `gis`, `ibm`, `kubernetes`, `oci`, `onprem`, `openstack`, `outscale`, `programming`, `saas`	MIT License	PNG icons from the Python diagrams library (also supplements `aws`, `azure`, `gcp` with PNG variants).

Note: This project does not claim ownership of any bundled icon files. The icons are provided as-is from their respective upstream sources for convenience in AI-assisted diagramming workflows. The MIT license of this project applies to the server code, search engine, tooling, and documentation — not to the third-party icon assets.

📄 License

Bundled icons: Each icon set retains its original license and terms as listed in Icon Sources & Attributions.

Name		Name	Last commit message	Last commit date
Latest commit History 9 Commits
.codegraph		.codegraph
.github/workflows		.github/workflows
docs		docs
scripts		scripts
tech_icons		tech_icons
tests		tests
.dockerignore		.dockerignore
.gitattributes		.gitattributes
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
README_zh.md		README_zh.md
docker-compose.yml		docker-compose.yml
docker-entrypoint.sh		docker-entrypoint.sh
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt
uv.lock		uv.lock

Folders and files

Latest commit

History

Repository files navigation