🚧 WORK IN PROGRESS

This project is under active development.
Expect frequent updates and breaking changes.

Brandfetch MCP Server

Model Context Protocol (MCP) server that lets AI assistants fetch logos, colors, fonts, and company info from the Brandfetch API.

Features

get_brand_details – Full brand profile by domain
search_brands – Keyword search for matching brands
get_brand_logo – SVG/PNG assets in light/dark themes
get_brand_colors – Curated color palettes with metadata
get_logo_url – Fast logo URL lookup by domain
Persistent usage tracking – SQLite-based quota management

Smart API Usage

This server prioritizes the Logo-by-Domain API (high quota, unlimited usage) and only falls back to the Brand API (limited quota) when necessary:

Domain lookup first - Direct logo-by-domain API calls with high usage limits
Brand API fallback - Only used when domain lookup fails, with monthly quota tracking
Persistent usage tracking - SQLite-based counter prevents quota overages
Warning system - Alerts when approaching Brand API limits

Requirements

Python 3.10+
Brandfetch API keys (both Logo and Brand API)
uv

API Key Setup

You need two API keys from Brandfetch:

Logo API Key (high quota, for domain lookups)
Brand API Key (limited quota, for fallback searches)

Add both to your .env file:

# Brandfetch API Configuration
# Get both keys from https://brandfetch.com/developers

# Logo API Key (high quota, for domain lookups)
BRANDFETCH_CLIENT_ID="paste_logo_key_here"

# Brand API Key (limited quota, for fallback searches)
BRANDFETCH_API_KEY="paste_brand_key_here"

Quickstart (one page)

Get the right API keys
Visit https://brandfetch.com/developers and get both keys:
- Logo API Key - For high-quota domain lookups
- Brand API Key - For fallback searches (limited quota)
  → Need screenshots? See API_KEY_SETUP.md.

Run locally with Python

uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"
cp .env.example .env  # then add both BRANDFETCH_CLIENT_ID and BRANDFETCH_API_KEY
python manual_test.py

Run with Docker (optional)

docker build -t brandfetch-mcp .
docker run --rm \
  -e BRANDFETCH_CLIENT_ID=paste_logo_key \
  -e BRANDFETCH_API_KEY=paste_brand_key \
  brandfetch-mcp

Wire up Claude Desktop

{
  "mcpServers": {
    "brandfetch": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/brandfetch_mcp", "run", "mcp-brandfetch"],
      "env": { 
        "BRANDFETCH_CLIENT_ID": "paste_logo_key",
        "BRANDFETCH_API_KEY": "paste_brand_key"
      }
    }
  }
}

Restart Claude Desktop; look for the hammer icon.

Project Structure

Key files:

src/brandfetch_mcp/server.py: Main MCP server implementation
src/brandfetch_mcp/client.py: Brandfetch API client
src/brandfetch_mcp/brandfetch_logo_lookup_checked.py: Logo lookup functionality

Usage

Quick health check

curl -H "Authorization: Bearer YOUR_KEY" https://api.brandfetch.io/v2/brands/github.com

Handy prompts

"Get brand details for stripe.com"
"Search for coffee brands"
"Fetch the SVG logo for github.com"
"What color palette does netflix.com use?"
"Get a logo URL for github.com" (fast domain lookup)
"Find the logo for GitHub" (name search with heuristics)

Testing Workflow

Automated Testing

# Run all tests
pytest tests/

# Run specific test file
pytest tests/test_client.py -v

Manual Verification

Start the MCP server:
```
uv run mcp-brandfetch
```

In a new terminal, test with MCP Inspector:

npx @modelcontextprotocol/inspector uv --directory $(pwd) run mcp-brandfetch

Verify basic functionality:

# Health check
curl http://localhost:8000/health

# Brand lookup
curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{"method":"get_brand_details","params":{"domain":"github.com"}}'

Tools Integration

Windsurf

Ensure MCP server is running
Open MCP tools panel
Connect to localhost:8000
Test with example queries

Goose

Add new MCP server connection
Configure:
- Host: localhost
- Port: 8000
- Path: Project directory
Save and test connection

Contributing

Fork the repository
Create your feature branch (git checkout -b feature/fooBar)
Commit your changes (git commit -am 'Add some fooBar')
Push to the branch (git push origin feature/fooBar)
Create a new Pull Request

License

MIT

Troubleshooting

Issue	Fix
401 Unauthorized	You grabbed the Logo API key—generate the Brand API key instead.
No hammer icon in Claude	Check Claude Desktop → Settings → Developer logs; verify JSON and absolute paths.
Import errors	Activate the venv and rerun `uv pip install -e ".[dev]"`.

Known Limitations

Development Mode: Must run from project root directory (.env path resolution works in development mode only)
Test Coverage: Some get_brand_logo tests mock wrong layer - functionality works but tests need updating
Pip Installation: Environment file loading only works when running from source, not pip-installed packages

Support

Open GitHub issues for bugs/requests
Brandfetch API docs
Model Context Protocol
More setup detail: API_KEY_SETUP.md