🚧 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:

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

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