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:

1. Domain lookup first - Direct logo-by-domain API calls with high usage limits

2. Brand API fallback - Only used when domain lookup fails, with monthly quota tracking

3. Persistent usage tracking - SQLite-based counter prevents quota overages

4. 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:

1. Logo API Key (high quota, for domain lookups)

2. 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)

1. 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.

2. 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

3. 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

4. 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

1. Start the MCP server:

   uv run mcp-brandfetch

2. In a new terminal, test with MCP Inspector:

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

3. 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

1. Ensure MCP server is running

2. Open MCP tools panel

3. Connect to localhost:8000

4. Test with example queries

Goose

1. Add new MCP server connection

2. Configure:

   • Host: localhost

   • Port: 8000

   • Path: Project directory

3. Save and test connection

Contributing

1. Fork the repository

2. Create your feature branch (git checkout -b feature/fooBar)

3. Commit your changes (git commit -am 'Add some fooBar')

4. Push to the branch (git push origin feature/fooBar)

5. Create a new Pull Request

License

MIT

Troubleshooting

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