README.md•5.91 kB
<div align="center">
<img src="https://img.shields.io/badge/status-work--in--progress-yellow.svg" alt="WIP">
<h1>🚧 WORK IN PROGRESS</h1>
<p>This project is under active development.<br>
Expect frequent updates and breaking changes.</p>
<hr>
</div>
# 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](https://astral.sh/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:
```bash
# 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](API_KEY_SETUP.md).
2. **Run locally with Python**
```bash
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)**
```bash
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**
```json
{
"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
```bash
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
```bash
# Run all tests
pytest tests/
# Run specific test file
pytest tests/test_client.py -v
```
### Manual Verification
1. Start the MCP server:
```bash
uv run mcp-brandfetch
```
2. In a new terminal, test with MCP Inspector:
```bash
npx @modelcontextprotocol/inspector uv --directory $(pwd) run mcp-brandfetch
```
3. Verify basic functionality:
```bash
# 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](LICENSE)
## 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](https://docs.brandfetch.com)
- [Model Context Protocol](https://modelcontextprotocol.io)
- More setup detail: [API_KEY_SETUP.md](API_KEY_SETUP.md)