<div align="center">

# Asset Finder MCP

**The all-in-one asset search MCP server for AI coding agents**

Find icons, logos, stock photos, vectors, and emoji — all from a single tool call.

[![CI](https://github.com/Erfangit23/asset-finder-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Erfangit23/asset-finder-mcp/actions/workflows/ci.yml)
[![npm version](https://img.shields.io/npm/v/asset-finder-mcp.svg)](https://www.npmjs.com/package/asset-finder-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js](https://img.shields.io/badge/Node.js-18%2B-green.svg)](https://nodejs.org)

</div>

---

## Why?

AI coding agents (Cursor, Claude Code, Windsurf, Cline) build UIs every day — but when they need an icon, a logo, or a stock photo, the human has to go find it manually. **Asset Finder MCP fixes this.** Your AI agent can now search 700,000+ assets and pick the right one, in real-time, without leaving the editor.

## What It Does

| Tool | Description | Sources |
|------|-------------|---------|
| `search_icons` | Search 200,000+ UI icons | Iconify |
| `search_logos` | Find brand & company logos | Logo.dev |
| `search_stock_photos` | Search free stock photography | Pexels, Unsplash, Pixabay |
| `search_vectors` | Search 500,000+ SVG vectors | SVG Repo |
| `search_emoji` | Search open-source emoji | OpenMoji |
| `suggest_asset` | Describe what you need → get ranked matches | All sources |
| `get_asset` | Get full details for a specific asset | All sources |
| `list_providers` | Show available asset sources | — |

## Quick Start

### One-line install (no API keys needed):

```json
{
  "mcpServers": {
    "asset-finder": {
      "command": "npx",
      "args": ["-y", "asset-finder-mcp"]
    }
  }
}
```

That's it. The server starts immediately with 3 free providers (Iconify, SVG Repo, OpenMoji) — no signup, no keys, no config.

### With stock photos and logos (optional API keys):

```json
{
  "mcpServers": {
    "asset-finder": {
      "command": "npx",
      "args": ["-y", "asset-finder-mcp"],
      "env": {
        "PEXELS_API_KEY": "your-key",
        "UNSPLASH_ACCESS_KEY": "your-key",
        "PIXABAY_API_KEY": "your-key",
        "LOGO_DEV_TOKEN": "your-token"
      }
    }
  }
}
```

Get free API keys:
- **Pexels** — https://www.pexels.com/api/
- **Unsplash** — https://unsplash.com/developers
- **Pixabay** — https://pixabay.com/api/docs/
- **Logo.dev** — https://logo.dev

## Install in Your Editor

<details>
<summary><b>Claude Desktop</b></summary>

Edit `claude_desktop_config.json`:

- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "asset-finder": {
      "command": "npx",
      "args": ["-y", "asset-finder-mcp"]
    }
  }
}
```
</details>

<details>
<summary><b>Cursor</b></summary>

Create `.cursor/mcp.json` in your project root:

```json
{
  "mcpServers": {
    "asset-finder": {
      "command": "npx",
      "args": ["-y", "asset-finder-mcp"]
    }
  }
}
```
</details>

<details>
<summary><b>Windsurf</b></summary>

Edit `~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "asset-finder": {
      "command": "npx",
      "args": ["-y", "asset-finder-mcp"]
    }
  }
}
```
</details>

<details>
<summary><b>VS Code (Cline / Continue)</b></summary>

Add to your MCP settings:

```json
{
  "mcpServers": {
    "asset-finder": {
      "command": "npx",
      "args": ["-y", "asset-finder-mcp"]
    }
  }
}
```
</details>

<details>
<summary><b>Local Development</b></summary>

```bash
git clone https://github.com/Erfangit23/asset-finder-mcp.git
cd asset-finder-mcp
npm install
npm run build
npm start
```
</details>

## The `suggest_asset` Tool (The Killer Feature)

Instead of knowing which tool to call, just describe what you need:

```
"suggest_asset" with description: "modern minimalist icon for a settings menu, blue color"
→ searches Iconify + SVG Repo, returns ranked results

"suggest_asset" with description: "Stripe company logo"
→ searches Logo.dev, returns the Stripe logo

"suggest_asset" with description: "professional headshot photo for a team page"
→ searches Pexels + Unsplash + Pixabay, returns photos

"suggest_asset" with description: "cute cat emoji"
→ searches OpenMoji, returns matching emoji
```

The tool auto-detects the asset type from your description and searches the right providers.

## Example: AI Agent Workflow

1. **You ask Cursor:** "Build a settings page with a gear icon and a mountain background image"
2. **Cursor calls:** `suggest_asset("gear settings icon")` → gets SVG icon URL
3. **Cursor calls:** `suggest_asset("mountain landscape background")` → gets stock photo URL
4. **Cursor writes:** The full HTML/CSS with real assets embedded — no placeholders

## Asset Catalog

| Source | Type | Count | API Key | License |
|--------|------|-------|---------|---------|
| Iconify | Icons | 200,000+ | No | Various (per icon set) |
| SVG Repo | Vectors | 500,000+ | No | Various (CC0, CC-BY, etc.) |
| OpenMoji | Emoji | 4,000+ | No | CC BY-SA 4.0 |
| Pexels | Stock Photos | Millions | Yes | Free for commercial use |
| Unsplash | Stock Photos | Millions | Yes | Unsplash License |
| Pixabay | Photos & Vectors | 2M+ | Yes | Pixabay Content License |
| Logo.dev | Brand Logos | 50,000+ | Yes | Free for commercial use |

## Features

- **Zero-config start** — works immediately with 3 free providers, no signup
- **Multi-source aggregation** — one tool call, results from all providers
- **AI-friendly output** — license info, dimensions, format, tags in every result
- **License-aware filtering** — filter by MIT, CC0, CC-BY, commercial-use, etc.
- **Smart suggestion** — describe in natural language, get the right asset type
- **In-memory caching** — LRU cache reduces API calls and latency
- **TypeScript** — fully typed, declaration files included
- **Tested** — unit tests for cache, normalization, and filtering

## Project Structure

```
asset-finder-mcp/
├── src/
│   ├── index.ts                  # MCP server entry point
│   ├── config.ts                 # Environment config loader
│   ├── types.ts                  # Shared type definitions
│   ├── tools/
│   │   ├── search-tools.ts       # search_icons, search_logos, search_stock_photos, search_vectors, search_emoji
│   │   ├── suggest-asset.ts      # suggest_asset (smart multi-provider search)
│   │   ├── get-asset.ts          # get_asset (fetch by ID)
│   │   └── list-providers.ts     # list_providers (show available sources)
│   ├── providers/
│   │   ├── iconify.ts            # 200k+ icons (free, no key)
│   │   ├── svgrepo.ts            # 500k+ SVG vectors (free, no key)
│   │   ├── openmoji.ts           # Open-source emoji (free, no key)
│   │   ├── pexels.ts             # Stock photos (free, key needed)
│   │   ├── unsplash.ts           # Stock photos (free, key needed)
│   │   ├── pixabay.ts            # Photos & vectors (free, key needed)
│   │   └── logo-dev.ts           # Brand logos (free, token needed)
│   └── utils/
│       ├── cache.ts              # LRU cache
│       ├── normalize.ts          # Result normalization & AI formatting
│       └── license-filter.ts     # License/format/color filtering
├── tests/
│   ├── cache.test.ts
│   ├── normalize.test.ts
│   └── license-filter.test.ts
├── examples/
│   ├── claude-desktop.json
│   ├── cursor-config.json
│   └── windsurf-config.json
├── docs/
│   ├── INSTALL.md
│   └── PROVIDERS.md
├── .github/workflows/ci.yml
├── .env.example
├── package.json
├── tsconfig.json
└── LICENSE
```

## Contributing

Contributions are welcome! Here's how to add a new provider:

1. Create `src/providers/your-provider.ts` implementing the `Provider` interface
2. Register it in `src/index.ts`
3. Add tests
4. Update `docs/PROVIDERS.md`
5. Submit a PR

## License

MIT — see [LICENSE](LICENSE)

## Links

- **MCP Specification:** https://modelcontextprotocol.io
- **MCP SDK:** https://github.com/modelcontextprotocol/typescript-sdk
- **Report an issue:** https://github.com/Erfangit23/asset-finder-mcp/issues

---

<div align="center">

**If this project helped you, give it a star!**

</div>