Metadata-Version: 2.4
Name: brandfetch
Version: 0.4.0
Summary: Fetch brand data from Brandfetch.com
Author: alfa-rsa
License-Expression: MIT
Project-URL: Homepage, https://github.com/alfa-rsa/brandfetch
Project-URL: Repository, https://github.com/alfa-rsa/brandfetch
Project-URL: Issues, https://github.com/alfa-rsa/brandfetch/issues
Keywords: brandfetch,brand,logo,colors,whois,mcp,cli
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: scrapling[all]
Requires-Dist: typer[all]
Requires-Dist: rich
Requires-Dist: mcp>=2.0
Dynamic: license-file

# brandfetch

A command-line tool and MCP server that pulls brand details — logos, colors, description, company info, social links and WHOIS registration data — for a given domain, served up from what Brandfetch publishes.

> **Not the official Brandfetch software.** This is an independent side project. It is not affiliated with, endorsed by, or sponsored by Brandfetch. "Brandfetch" is a trademark of Brandfetch Ltd, and all brand data shown by this tool belongs to its respective owners.

## Install

```bash
pip install brandfetch
```

Requires Python 3.10+. On first use the tool downloads a headless browser, which it drives to read brand pages without tripping bot detection.

## Usage

Look up a company by its domain:

```bash
brandfetch nike.com
```

If the argument has no dot, it's treated as a search instead:

```bash
brandfetch nike
```

| Flag              | Meaning                        |
| ----------------- | ------------------------------ |
| `-j, --json`      | print raw JSON                 |
| `-m, --md`        | print Markdown                 |
| `-v, --version`   | show version and exit          |
| `-h, --help`      | show help and exit             |
| `--mcp`           | run the MCP server on stdio    |

Example of the JSON output:

```json
{
  "name": "OpenAI",
  "domain": "openai.com",
  "description": "Open AI is an AI research and deployment company dedicated to ensuring...",
  "logos": [
    "https://cdn.brandfetch.io/idR3duQxYl/theme/dark/logo.svg",
    "https://cdn.brandfetch.io/idR3duQxYl/theme/light/logo.svg"
  ],
  "colors": [
    "#080808",
    "#ffffff"
  ],
  "industry": "Science and Education",
  "company_type": "Partnership",
  "year_founded": "2015",
  "company_size": "1001-5000 employees",
  "social_links": [
    { "platform": "twitter", "url": "https://twitter.com/openai" },
    { "platform": "github",  "url": "https://github.com/openai" }
  ],
  "related": ["elevenlabs.io", "wiley.com"],
  "whois": {
    "registrar": "MarkMonitor Inc.",
    "creation_date": "2007-01-19T19:28:24+00:00",
    "expiration_date": "2029-01-19T19:28:24+00:00",
    "name_servers": ["ns1-02.azure-dns.com"],
    "organization": "OpenAI",
    "country": "US"
  }
}
```

## Use with your agent

`brandfetch --mcp` exposes three tools over the Model Context Protocol:

| Tool            | What it returns                              |
| --------------- | -------------------------------------------- |
| `lookup_brand`  | full brand profile for a domain              |
| `search_brands` | matching brands for a name or keyword        |
| `whois_lookup`  | WHOIS record for a domain                    |

After `pip install brandfetch` the command is `brandfetch --mcp`; when running from a checkout use `python -m brandfetch.cli --mcp`.

One caveat across all of the setups below: domain lookups drive a real headless browser and can take 10-80s. If your agent has a per-tool timeout, raise it or the lookup will be killed mid-flight.

### opencode

Project `opencode.json`, or the global `~/.config/opencode/opencode.json`:

```json
{
  "mcp": {
    "brandfetch": {
      "type": "local",
      "command": ["brandfetch", "--mcp"],
      "enabled": true,
      "timeout": 300000
    }
  }
}
```

The `timeout` is in milliseconds.

### Claude Code

One command (add `--scope user` to make it available in every project):

```bash
claude mcp add brandfetch -- brandfetch --mcp
```

Or write a project-scoped `.mcp.json` so the whole team shares it:

```json
{
  "mcpServers": {
    "brandfetch": { "command": "brandfetch", "args": ["--mcp"] }
  }
}
```

### Claude Desktop

Add to `claude_desktop_config.json` (`%APPDATA%\Claude\` on Windows, `~/Library/Application Support/Claude/` on macOS):

```json
{
  "mcpServers": {
    "brandfetch": { "command": "brandfetch", "args": ["--mcp"] }
  }
}
```

### Codex (OpenAI Codex CLI)

Edit `~/.codex/config.toml` (the same file is shared by the Codex CLI, the ChatGPT desktop app, and the IDE extension):

```toml
[mcp_servers.brandfetch]
command = "brandfetch"
args = ["--mcp"]
enabled = true
startup_timeout_sec = 30
tool_timeout_sec = 300
```

Codex defaults `tool_timeout_sec` to 60, which is too short for a browser-backed lookup.

## How it works

- **Domain lookups** — a stealth headless browser visits `brandfetch.com/<domain>` and reads the page directly.
- **WHOIS** — queried over the WHOIS protocol (TCP port 43), so it works even when the main site is unreachable.

## Tech stack

[![Python](https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
[![Typer](https://img.shields.io/badge/Typer-0C8DA4)](https://typer.tiangolo.com/)
[![Rich](https://img.shields.io/badge/Rich-A05A2C)](https://github.com/Textualize/rich)
[![Scrling](https://img.shields.io/badge/Scrling-2C3E50)](https://github.com/D4Vinci/Scrling)
[![MCP](https://img.shields.io/badge/MCP_SDK-6D28D9)](https://modelcontextprotocol.io/)

- **Typer** — CLI framework
- **Rich** — terminal output
- **Scrling** — stealth headless-browser scraping (via the `scrapling` package)
- **MCP Python SDK** — LLM tool server

## Development

```bash
python -m pytest tests/test_cli.py tests/test_mcp.py
python test_mcp_manual.py   # spins up the MCP server over stdio and pokes it
```

## License

MIT. See [LICENSE](LICENSE).
