Brandfetch MCP Server & CLI

What is the Brandfetch MCP server & CLI?

The Brandfetch MCP server & CLI is a free, open source program that lets AI agents read brand data and context, enrich a requested descriptor and carry out approved prefetch/private downloads for you, in 2 ways. The MCP server is what an AI app like Claude, Codex or Cursor connects to, through MCP (Model Context Protocol), the open standard AI apps use to call outside tools.

You ask in plain language. Your AI picks the right tool, and the server makes the call directly to the fixed Brandfetch API; approved original assets use its allowed CDN.

The CLI is the same program as commands. brandfetch-cli get-brand runs the same code your AI runs when you deliberately retrieve the intended brand using the selected profile, whether an agent like Claude Code runs it or you do.

What can you ask it?

Once it's set up, you ask the way you'd ask an assistant. These are real prompts it handles:

Try asking
Search for this brand and let me select the intended domain.
Read only this brand’s colors without exposing asset credentials.
Compare these two requested brands in the work profile.
Read cached interpreted context and tell me if it is a cache miss.
Enrich this specific transaction label and country; do not make a payment.
Queue one approved brand prefetch.
Save at most two approved original logos in my private directory.

Brandfetch already offers a capable official OAuth/MCP Apps server and existing community CLIs. This owned companion adds a shared task CLI/local MCP with isolated named profiles, bounded ordered comparisons, selective credential-free output and approved exclusive private files. Official hosted OAuth, rich cards and image resources remain useful alternatives.

How to install the Brandfetch MCP server

Choose the shared task CLI, local MCP or versioned desktop bundle in the existing install controls. Codex is the primary documented agent; the complete client and OS setup follows below.

Set up Brandfetch access

Two separate provider credentials

1. Open the Brandfetch developer portal. Obtain a Brand API key for brand data, context, transaction enrichment, prefetch and viewer reads. Check the account's current plan and quota.
2. Obtain a separate Logo API client ID for Brand Search and browser-displayed Logo API URLs. It identifies the application and belongs in those browser URLs; it is not a Brand API Bearer key.
3. Store the Brand API key outside repositories in an absolute owner-only token-only file, or configure BRANDFETCH_API_KEY in private local settings. Configure BRANDFETCH_CLIENT_ID separately. Official MCP bf1 tokens and hosted OAuth sessions are different credentials; do not pass them as REST API keys.
4. Run brandfetch-cli doctor for local settings/presence. Deliberately run doctor --network to read the selected Brand API viewer; this verifies that request, not every feature or client. For a client-ID-only profile, test search instead of the Brand API viewer.
5. Read the exact requested brand. Choose cachedOnly=true when a cache miss should remain a 204 without crawling. Approve prefetch or a private download only when requested.

Brand API keys go only to the fixed api.brandfetch.io REST origin in Authorization: Bearer. Search uses native query c and sends no Bearer header. Named profiles never inherit global keys or client IDs. login prints setup instructions; it does not open a browser, store credentials, purchase access, refresh tokens or implement OAuth. This package does not load .env files or official MCP sessions automatically.

On macOS/Linux, use an existing owner-private directory (0700) and a regular non-symlink token-only file (0600) at an absolute path, at most 64 KiB. Token-file credentials override the profile environment key and are cached until restart. On Windows, restrict file/directory ACLs to your user; POSIX mode checks do not validate Windows ACL protection. GUI apps and remote development environments may not inherit the terminal environment.

Plans, quota and paid reads

The AGPL wrapper is free. Brandfetch access, brand/context/transaction credits and provider terms remain separate. Check current pricing and your dashboard before using the API. Indexed Brand API reads can consume quota. A read may crawl on a cache miss unless cachedOnly=true. Local colors/fonts filtering and CLI --select reduce output only, not provider calls, bytes or credits.

Brand Search and Logo API use their own client-ID contract. Current Logo API documentation describes one million monthly hotlink requests on the free tier, with soft limits and traffic ceilings; this does not make Brand API reads free. Account eligibility, quotas and limits can change. HTTP 402/429 indicate payment/quota/rate constraints; a 403 with an explicit quota/credit/limit detail maps to exit 7, while ordinary 401/403 map to authentication/permission exit 4. HEAD errors may contain no JSON detail; inspect provider settings and status rather than assuming the cause.

The default local 200 ms pacing is per profile/process across API and asset requests, not a provider-wide quota reservation. Other processes and profiles using the same key share upstream limits. No request automatically retries on a timeout, redirect, 429 or 5xx. JSON bodies are capped at 1 MiB; each API response and asset at 5 MiB. Asset requests have a maximum five-second timeout. Comparisons make two to five ordered reads; downloads make one brand read and up to five original asset GETs.

Logo hotlinks versus private assets

get_logo_url constructs browser-display URLs locally. The provider blocks programmatic fetching of Logo API client-ID hotlinks. Do not spoof browser headers or download these URLs with scripts. For local files, download_brand_logos uses only original credentialed src URLs returned by the Brand API, preserving their path and per-request credential. API keys are never forwarded to the CDN. Redirects, arbitrary hosts, hotlink routes and missing/duplicated c parameters refuse.

Brand API src credentials are redacted from model output, including ordinary get_brand results. This preserves asset metadata but deliberately changes the legacy behavior of returning all credentialed src strings. The official MCP provides interactive cards and a bounded image resource stream when those capabilities are needed. Downloaded SVGs/images remain untrusted files; this wrapper does not execute or automatically render them.

Rotate and revoke

Rotate or revoke the intended Brand API key in Brandfetch, update private settings/files and restart clients. Update the client ID separately if its application configuration changes. Uninstalling npm does not revoke access, undo a provider crawl or delete private downloaded assets. Keep private profiles, keys, viewer metadata and per-request URLs out of public issues, screenshots and logs.

Check that it works

Run local checks, then deliberately verify the Brand API viewer using the selected private profile.

brandfetch-cli --version
brandfetch-cli doctor
brandfetch-cli doctor --network
brandfetch-cli list-accounts --agent
brandfetch-cli get-viewer --agent

brandfetch-cli doctor
brandfetch-cli doctor --network
brandfetch-cli list-accounts --agent
brandfetch-cli get-viewer --agent
brandfetch-cli get-brand --identifier example.com --cachedOnly --agent

Local doctor reports settings/presence and does not authenticate. Network doctor deliberately reads the selected Brand API viewer. A client-ID-only profile can search and construct browser URLs but cannot make Brand API reads. Cached misses are reported as status 204 / cachedMiss:true / data:null. Do not queue crawls or download assets merely to test installation. Read-only discovery returns 12 tools and refuses direct confirmed writes.

Use the Brandfetch CLI

The CLI is the same 14 tools as commands. AI agents that run commands, like Claude Code, Codex and OpenCode, use it on their own, and you can type the same commands in a terminal or a script.

Every tool name becomes a command with dashes, so get_brand runs as brandfetch-cli get-brand.

brandfetch-cli tools
brandfetch-cli get-brand --help
brandfetch-cli schema get-brand
brandfetch-cli get-brand --identifier example.com --cachedOnly --agent
brandfetch-cli get-brand-colors --identifier example.com --cachedOnly --agent

The bare brandfetch-cli lists every command, and brandfetch-cli <command> --help shows what a command takes. Both prefetch and private downloads require --confirm. --agent/--yes never approve execution. A read can still spend quota or crawl; native cachedOnly controls supported cache misses.

These flags work on every command:

A script can branch on the exit code:

MCP server or CLI: which one?

Both surfaces call the same tools. Codex can connect to the local MCP server or run the CLI directly. Neither requires Claude Code.

MCP provides structured tool discovery; the CLI supports scripts, compact JSON, field selection and command/schema discovery. Official hosted MCP connection and local CLI authentication have different setup requirements.

Codex-specific token measurements are pending. Record the actual client/model versions, discovery configuration, input/output usage, caching, latency and equivalent successful outcomes. Standing definitions and full task cost are separate measurements; CLI commands, selected help, results and reasoning still consume tokens.

No efficiency percentage or Claude-derived figure is presented as a Codex result. Other-client benchmarks can be added separately.

Brand, context and transaction workflows

Resolve the requested identifier

Search returns candidate brands; select the intended domain before fetching. Generic lookup accepts domains, email addresses, URLs, Brand IDs, tickers, ISINs and crypto symbols. Provider resolution order is domain → ticker → ISIN → crypto; explicit identifier_type routes avoid ambiguity. Email/URL lookup resolves a registrable domain and does not establish that the domain is the person's employer. Explicit domain routes reject email/URL inputs locally.

brandfetch-cli search-brands --query Example --agent
brandfetch-cli get-brand --identifier example.com --identifier-type domain --cachedOnly --agent
brandfetch-cli get-brand-colors --identifier example.com --cachedOnly --agent
brandfetch-cli get-brand-fonts --identifier example.com --cachedOnly --agent
brandfetch-cli get-brand --identifier BTC --identifier-type crypto --agent

Context and enrichment

Brand Context returns interpreted positioning, voice and related information. Treat it as probabilistic interpretation requiring review. Use only the transaction descriptor requested by the user; it is sent to Brandfetch. This is a brand resolution API, not a payment or bank account workflow.

brandfetch-cli get-brand-context --domain example.com --cachedOnly --agent
brandfetch-cli enrich-transaction --transaction-label "EXAMPLE CAFE" --country-code US --agent

Explicit prefetch

prefetch_brand requires confirmation because HEAD can queue crawling. A 200 reports indexed and 202 reports crawlQueued; it does not guarantee a future lookup result, initiate polling or prove completion. There is no automatic payment, fallback purchase or wallet support.

brandfetch-cli prefetch-brand --identifier example.com --confirm --agent

Bounded comparison, private downloads and browser logos

Ordered comparison

compare_brands accepts two to five unique identifiers, prevalidates all of them before the first request, then reads sequentially in one exact selected profile. It returns name/domain/colors/fonts/logo counts and qualityScore, preserving input order. A 204 remains an explicit cache miss. A failure stops subsequent requests and reports completed results plus the failed/remaining identifiers. Earlier reads may have consumed quota. There is no persistent result cache, completeness claim or automatic continuation.

brandfetch-cli compare-brands --identifiers example.com --identifiers example.org --account work --cachedOnly --agent

Approved private files

Create an owner-private directory yourself before requesting a download. output_dir must be absolute, canonical and already present. Symlink directories and public POSIX permissions refuse before the brand lookup; Windows owners must restrict ACLs. No automatic directory creation or hidden default output directory is used.

mkdir -m 700 /absolute/private/brand-assets
brandfetch-cli download-brand-logos --identifier example.com --output-dir /absolute/private/brand-assets --format-preference svg --max-files 2 --confirm --agent

The helper performs one brand read, selects matching logo formats in provider order and downloads at most max_files (default three, maximum five). format_preference supports svg/png/all; all allows documented SVG, PNG, JPEG, WebP and GIF asset formats. Selection is bounded, not all-assets export. Each original credentialed CDN URL is validated before the first file download. Fixed allowed HTTPS CDN only; no redirects, key forwarding, browser-header spoofing or hotlink downloads. Each response is streamed under a 5 MiB cap and image Content-Type must match the selected declared format.

Files use random exclusive names and 0600 creation; existing files are never overwritten. SHA-256, actual bytes, format and local path are returned; credential URLs are not written to a manifest or model output. A failure stops subsequent downloads and reports completed files plus any reserved path; the reserved file may be empty or incomplete. Inspect it privately rather than retrying blindly. No rollback deletes earlier completed files, and nothing executes or previews downloaded SVGs.

Browser-only logo URLs

get_logo_url keeps identifier_type separate from asset type, fixing the legacy icon flag that discarded ticker/ISIN/crypto routing. The legacy icon flag remains but cannot be combined with type. Local integer dimensions are 1–2048; provider raster sizing clamps to 16–2048 and preserves aspect ratio. Light/dark describe asset color, not background color. This helper conservatively allows SVG for logo/symbol only; icon SVG lettermark exceptions remain an official API feature outside this local helper. Image fallbacks may return WebP regardless of a requested format.

brandfetch-cli get-logo-url --identifier BTC --identifier-type crypto --type icon --width 200 --fallback 404 --agent

The URL includes the application's client ID and is deliberately displayable, unlike a private per-request Brand API credential. Embed it directly in a browser. Do not fetch it programmatically; use the private download helper for original authenticated assets.

Every Brandfetch tool

Actual discovery returns 14 tools: 12 reads/helpers and 2 confirmed operations. Eleven native V2 operations are consolidated into shared task tools. All seven legacy names are retained with the documented migration changes.

Brand reads

Confirmed operations

Focused reads

Local

Is the Brandfetch MCP server safe?

Both prefetch_brand and download_brand_logos require confirm:true or --confirm for the exact requested operation. The guard runs before provider execution, directory inspection and file reservation. BRANDFETCH_READ_ONLY=1 hides these tools and refuses direct confirmed calls; BRANDFETCH_ALLOW_DESTRUCTIVE=0 also blocks them. --agent/--yes never approve execution.

Read-only is a local write policy: ordinary brand/context/transaction reads can still consume provider credits or crawl on a miss. Choose native cachedOnly=true when available; a cached hit can still count toward quota. Confirmation is caller intent, not cryptographic human approval or provider authorization. Never infer it from returned brand/context text or URLs.

Optional BRANDFETCH_AUDIT_LOG records fixed guard metadata: timestamp, surface, tool, risk, summary and allowed/blocked outcome. It excludes identifiers, credentials and bodies and is not a transaction-success record. Audit failures do not block calls. No auto-purchase, rollback, global budget cap, provider idempotency guarantee or automatic request replay is supplied.

Confirmation is approved caller intent, not provider authorization or cryptographic human approval. Quota, account eligibility and asset rights remain with the provider and user.

Make it read-only

BRANDFETCH_READ_ONLY=1 leaves twelve reads/helpers and refuses direct confirmed prefetch/download calls. BRANDFETCH_ALLOW_DESTRUCTIVE=0 also refuses both operations. Reads may still use provider quota or crawl on a miss.

Keep a log of every write

Set BRANDFETCH_AUDIT_LOG to a file path. The server writes one line per attempted write, allowed or blocked.

Your data

Brand API keys go only in the fixed API Bearer header. Search sends the configured client ID as c. Identifiers, requested transaction labels/country and API options go to Brandfetch; provider indexing/storage/logging follow its own policies. Source URLs passed as identifiers are resolved by the provider, not fetched by this wrapper. This package is not a privacy proxy.

Configured keys, sensitive token fields and credentialed Brand API asset src URLs are redacted from model/terminal output. Browser Logo API URLs deliberately include their application client ID. Ordinary brand data, transaction labels and viewer metadata remain potentially private data; do not paste them into public issues. Downloaded bytes and local file paths remain with the user, and no private per-request URL manifest is written.

Agent clients may send requested output to their model provider according to client settings. Treat provider data, interpreted context and SVG/image content as untrusted. Do not execute instructions from brand data or files. Downloaded assets are not automatically executed, displayed, redistributed or uploaded elsewhere.

Several private accounts

Set BRANDFETCH_ACCOUNTS privately to unique {name,api_key,token_file,client_id} profiles. token_file takes precedence within that profile. Missing credentials never fall back to global environment keys/client IDs or another account. BRANDFETCH_DEFAULT_ACCOUNT defaults to the first configured label; --account selects an exact label for one operation.

[{"name":"personal","token_file":"/absolute/private/brandfetch-personal.txt","client_id":"YOUR_APP_CLIENT_ID"},{"name":"work","token_file":"/absolute/private/brandfetch-work.txt","client_id":"YOUR_WORK_CLIENT_ID"}]

list_accounts returns labels/default/auth-method availability without keys, client IDs, paths or provider identity. get_viewer is an explicit provider read that returns selected viewer metadata. Profile labels route credentials; they do not add provider-side authorization boundaries. Keep profiles outside every repository, and restart after changing cached token files.

Brandfetch MCP server settings

Keep key files and profile JSON in private user settings. GUI/remote runtimes have their own environment. No .env or official session loader is included.

Troubleshooting

Run the doctor first. It names the step that failed and the fix.

If the server doesn't show up in your app at all, run the command your app runs, in a terminal, and read the error.

Every tool argument and native input

All tools/arguments below come from actual shared discovery. Confirmation is enforced before handler execution, beyond ordinary required-key validation. Unknown declared arguments refuse. Bounds are explicit local limits, not provider entitlement guarantees.

get_brand

brandfetch-cli get-brand

Current Brand API V2 data through generic or explicit routes. One request; credentialed asset src URLs are redacted from output. Provider reads may spend quota or crawl on a miss.

search_brands

brandfetch-cli search-brands

Search by name with the selected profile client ID in native query c. No Brand API Bearer key sent. One request; no pagination or retries.

get_brand_context

brandfetch-cli get-brand-context

One Brand Context API request. Context is probabilistic interpretation, not verified company facts. Accepts domain/email/URL; cachedOnly avoids crawling a miss.

enrich_transaction

brandfetch-cli enrich-transaction

Resolve the user-requested transaction label into brand data. Sends the label and country to Brandfetch and may consume credits; does not create a charge, bank connection or payment.

get_viewer

brandfetch-cli get-viewer

GET /v2/viewer using the selected private Brand API key. Returns provider viewer metadata; does not purchase access or expose the key.

prefetch_brand

brandfetch-cli prefetch-brand

Explicitly confirmed HEAD request can enqueue a provider crawl. Generic or domain route only. Return 200 indexed / 202 crawl queued; never poll, purchase or resubmit automatically.

get_brand_colors

brandfetch-cli get-brand-colors

One native brand read with only name, domain and colors returned. Filtering is local: provider quota and crawling behavior are unchanged.

get_brand_fonts

brandfetch-cli get-brand-fonts

One native brand read with only name, domain and fonts returned. Filtering is local: provider quota and crawling behavior are unchanged.

compare_brands

brandfetch-cli compare-brands

Read two to five unique identifiers sequentially in one exact profile, preserving input order. Return colors/fonts/logo counts; stop at the first failure with completed results. No retries, cross-account mixing or complete-market claim.

get_logo_url

brandfetch-cli get-logo-url

Local Logo API URL construction with the selected profile client ID. Direct browser display only; programmatic fetching these hotlinks is prohibited/blocked. No provider call or automatic download.

download_brand_logos

brandfetch-cli download-brand-logos

Confirmed one brand lookup plus at most five original credentialed Brand API logo src downloads. Owner-private directory and exclusive files only; cap 5 MiB each, fixed CDN, no redirects/Bearer forwarding/hotlink evasion/retries. Stop on failure, retain and report completed/reserved files.

list_accounts

brandfetch-cli list-accounts

Local labels, default and credential method availability only. No keys, client IDs, private paths or network.

get_operation_schema

brandfetch-cli get-operation-schema

Complete pinned Brandfetch path/query/body schema and documented response statuses for one of 11 supported native operations. Local only; agent purchases excluded.

preview_operation

brandfetch-cli preview-operation

Validate one exact native operation request locally, without loading keys/client IDs, contacting Brandfetch, reserving files or claiming provider validation or price. Search c is added from private profile at execution.

Complete native operations and request shapes

get_brand consolidates six GET routes through identifier_type; prefetch_brand consolidates two HEAD routes. get_operation_schema returns these exact native parameter/body facts. preview_operation uses native parameter names: search name; transaction payload.transactionLabel and payload.countryCode. Execution tools use their documented friendly flags. Search c is supplied from the private selected profile.

##### getBrandData

GET /v2/brands/{identifier}. Documented statuses: 200, 204, 400, 401, 402, 404, 429.

##### prefetchBrand

HEAD /v2/brands/{identifier}. Documented statuses: 200, 202, 400, 401, 403, 404, 429, 503.

##### getBrandDataByDomain

GET /v2/brands/domain/{domain}. Documented statuses: 200, 204, 400, 401, 402, 404, 429.

##### prefetchBrandByDomain

HEAD /v2/brands/domain/{domain}. Documented statuses: 200, 202, 400, 401, 403, 404, 429, 503.

##### getBrandDataByTicker

GET /v2/brands/ticker/{ticker}. Documented statuses: 200, 204, 400, 401, 402, 404, 429.

##### getBrandDataByIsin

GET /v2/brands/isin/{isin}. Documented statuses: 200, 204, 400, 401, 402, 404, 429.

##### getBrandDataByCrypto

GET /v2/brands/crypto/{symbol}. Documented statuses: 200, 204, 400, 401, 402, 404, 429.

##### searchBrands

GET /v2/search/{name}. Documented statuses: 429, 503, 200.

##### getBrandContext

GET /v2/context/{domain}. Documented statuses: 200, 204, 400, 401, 402, 404, 429.

##### getBrandFromTransaction

POST /v2/brands/transaction. Documented statuses: 200, 400, 401, 402, 404, 429, 503.

Native transaction JSON body:

##### getViewer

GET /v2/viewer. Documented statuses: 200, 401, 403.

Complete client, OS and desktop setup

Codex

Codex is the current validation priority. Private token paths must exist in the process or remote environment where the server runs.

codex mcp add brandfetch -- npx -y @thenavidm/brandfetch-mcp-cli@latest
codex mcp list

Account credentials must reach the server through private environment settings. codex mcp add --env NAME=value stores values in your local config, so never commit that config or put secrets in a shared command. In TOML, the equivalent server is:

[mcp_servers.brandfetch]
command = "npx"
args = ["-y", "@thenavidm/brandfetch-mcp-cli@latest"]
env_vars = ["BRANDFETCH_API_KEY", "BRANDFETCH_TOKEN_FILE", "BRANDFETCH_CLIENT_ID", "BRANDFETCH_ACCOUNTS", "BRANDFETCH_DEFAULT_ACCOUNT", "BRANDFETCH_READ_ONLY", "BRANDFETCH_ALLOW_DESTRUCTIVE"]

env_vars forwards those names from the environment available to Codex. If that environment does not contain them, configure private env settings locally. Codex can also call the CLI directly with SKILL.md and --agent output.

Claude Code

For a user-scoped connection, after privately configuring credentials:

claude mcp add --scope user brandfetch -- npx -y @thenavidm/brandfetch-mcp-cli@latest
claude mcp list

Use the client's private local environment settings for the account variable if they are not inherited. Claude's -e NAME=value registration option writes values into its config; only use it locally through your secret manager, with no shared command transcript. Never place credentials in a project .mcp.json. Reconnect and ask Claude to verify credentials.

Alternatively install the CLI, make SKILL.md available to Claude, and use shell commands. Registering both surfaces is optional.

Claude Desktop

Install the .mcpb extension

1. Download brandfetch-2.0.0.mcpb from GitHub Releases.
2. In a supported Claude Desktop build, open Settings > Extensions > Advanced settings > Install Extension… and select it.
3. Enter a private Brand API key in the sensitive setting, or an absolute private token-file path. Configure the separate client ID for search/browser URLs. Leave the unused credential method empty. Brand API requests use Authorization: Bearer at the fixed API origin; search uses the separate client ID. Use the intended Brand API key; named profiles are configured separately in private client environments.
4. Enable read-only if you want only the 12 read operations. Reconnect and ask for account verification.

The bundle includes production dependencies and no credentials. Use a regular private token-only file if you prefer file-based credentials. The manifest requires Node 22 or newer from a compatible host. Organization policy may restrict custom extensions. Manual bundle updates require installing the new version; no automatic directory updates are promised. GUI installation remains unverified separately from archive/protocol checks.

Manual config

Open Settings > Developer > Edit Config, or use your platform's config file:

{
  "mcpServers": {
    "brandfetch": {
      "command": "npx",
      "args": ["-y", "@thenavidm/brandfetch-mcp-cli@latest"],
      "env": {
        "BRANDFETCH_API_KEY": "YOUR_PRIVATE_API_KEY",
        "BRANDFETCH_TOKEN_FILE": "",
        "BRANDFETCH_CLIENT_ID": "YOUR_APP_CLIENT_ID"
      }
    }
  }
}

Replace the placeholders only in your private file. Merge the server entry into an existing mcpServers object instead of replacing other integrations. Fully quit and reopen Claude Desktop. Do not enable an extension and a manual entry with the same name; choose one route.

If a Windows launcher cannot execute npx directly, use "command": "cmd" with "args": ["/c", "npx", "-y", "@thenavidm/brandfetch-mcp-cli@latest"]. An absolute node executable and installed dist/index.js path also avoids launcher/PATH problems.

Cursor

Use private user settings at ~/.cursor/mcp.json, or Settings > Tools & MCP. Cursor documents environment interpolation and envFile support.

{
  "mcpServers": {
    "brandfetch": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@thenavidm/brandfetch-mcp-cli@latest"],
      "env": {
        "BRANDFETCH_API_KEY": "${env:BRANDFETCH_API_KEY}",
        "BRANDFETCH_TOKEN_FILE": "${env:BRANDFETCH_TOKEN_FILE}"
      }
    }
  }
}

The environment values must exist for the Cursor process. If you use envFile, keep that file private and outside version control. A project's .cursor/mcp.json must not contain actual credentials. Reconnect the server after saving.

VS Code and Copilot

Use MCP: Open User Configuration. VS Code uses servers and secure inputs, rather than a mcpServers root:

{
  "inputs": [
    {"type": "promptString", "id": "brandfetch-api-token", "description": "Brandfetch API key (leave empty for a private token file)", "password": true},
    {"type": "promptString", "id": "brandfetch-token-file", "description": "Optional private token-file path (leave empty for API key)"}
  ],
  "servers": {
    "brandfetch": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@thenavidm/brandfetch-mcp-cli@latest"],
      "env": {
        "BRANDFETCH_API_KEY": "${input:brandfetch-api-token}",
        "BRANDFETCH_TOKEN_FILE": "${input:brandfetch-token-file}"
      }
    }
  }
}

Start Brandfetch through the MCP controls, approve trust if prompted, and enter credentials in the private input prompts. Workspace .vscode/mcp.json may contain this placeholder-only structure, but never resolved secret values. Remote development runs the server in the selected remote environment, so local file paths refer to that environment.

Windsurf

Open Cascade's MCP settings or edit the private user file ~/.codeium/windsurf/mcp_config.json. Use the Claude Desktop manual mcpServers block above with your locally configured env values. See Windsurf's current MCP documentation. Restart or reconnect Brandfetch in Cascade; project files must not contain secrets.

Zed

Open Settings > AI > MCP Servers > Add Server > Add Local Server, or your user settings file. Zed uses context_servers:

{
  "context_servers": {
    "brandfetch": {
      "command": "npx",
      "args": ["-y", "@thenavidm/brandfetch-mcp-cli@latest"],
      "env": {
        "BRANDFETCH_API_KEY": "YOUR_PRIVATE_API_KEY",
        "BRANDFETCH_TOKEN_FILE": "",
        "BRANDFETCH_CLIENT_ID": "YOUR_APP_CLIENT_ID"
      }
    }
  }
}

Enter actual values only in private user settings. Check the active-server indicator before prompting. Do not wrap command and args inside a nested command object from older Zed examples.

Gemini CLI

Merge the Claude Desktop manual mcpServers block into your private ~/.gemini/settings.json. Configure the private credential values locally, then restart Gemini CLI and inspect /mcp. See Gemini CLI's MCP configuration. Its project settings must not contain real credentials. You can instead use the CLI from an agent shell.

Other local stdio clients use the same command and arguments, adapted to their config format. A client that only accepts a remote MCP URL cannot connect directly: this package does not ship a public HTTP listener. ChatGPT's remote connector setup is not a substitute for local stdio installation.

Docker

Build locally from the reviewed source; no prebuilt registry image is claimed:

git clone https://github.com/thenavidm/brandfetch-mcp-cli.git
cd brandfetch-mcp-cli
docker build -t brandfetch-mcp-cli .
docker run --rm -i -e BRANDFETCH_API_KEY brandfetch-mcp-cli

Cline and other local MCP clients

Use the client's Add MCP server flow with command npx, arguments -y and @thenavidm/brandfetch-mcp-cli@latest, stdio transport, and private local BRANDFETCH_API_KEY or BRANDFETCH_TOKEN_FILE settings. UI names depend on the installed client. Reconnect and discover tools before an account call. Browser-only clients need a remote HTTPS connector; use Brandfetch's official server rather than this local stdio command.

Output, flags and exit codes

MCP uses underscore names; CLI uses derived hyphen names from the same schemas and handlers. Both return native data unless a focused helper explicitly documents its wrapper. Per-request asset credentials and configured keys are removed before output.

brandfetch-cli get-brand --identifier example.com --agent --select name,domain,colors
brandfetch-cli compare-brands --identifiers example.com --identifiers example.org --cachedOnly --agent

Partial comparisons/download failures return errors and retain completed results/file paths inside the diagnostic. No automatic rollback or retry is performed. Native cachedOnly=true affects provider resolution; colors/fonts/--select affect only local output.

Official and community comparisons

Checked October 3, 2026. The actual Sourcescape published brand/search handlers ran with injected fetch and fixture-only credentials; no provider account was contacted. Their full fixture brand output retained a per-request credentialed asset src. Our equivalent fixture excludes that credential from output, routes named accounts without global fallback, derives CLI options from the same MCP schema and supports bounded comparison/private downloads. This demonstrates useful local workflow and output-policy differences, not overall product superiority.

The official MCP is a strong alternative when provider-managed OAuth, rich brand cards, resource streaming or feedback are the desired workflow. Its built_logo_urls supports multiple identifiers already. Our useful recurring task is scriptable brand/context/transaction retrieval and comparison across isolated accounts, followed by explicitly requested private file delivery. The shared MCP also makes those exact bounded local workflows available to stdio clients. More tool names and SEO alone do not justify this build.

The published OpenAPI search path embeds ?c={clientId}; this package routes c as a query parameter from the selected profile. The agent overview describes keyless search while the endpoint reference requires c; the package follows the endpoint's explicit client-ID contract and fails locally when it is missing. We have not tested credential-free provider search. Agent access/payment endpoints are deliberately excluded: no wallet, card, auto-purchase or credential rotation.

No matched successful Codex task/token measurements, live provider outcomes or desktop GUI installation are claimed. Source/fixture evidence is recorded separately from public artifact and CMS release checks. Official and community versions should be rechecked for every update.

Versions and legacy migration

Private legacy 1.0.0 declares seven MCP tools and no standalone task CLI. Private history remains separate; no earlier owned public npm/tag release is assumed. All seven names survive, but 2.0 intentionally changes unsafe/obsolete behavior:

BRANDFETCH_OUTPUT_DIR is retired; supply output_dir explicitly. CLI spelling uses hyphens while MCP names remain underscores. No automatic credential migration, payment or key rotation. Preserve and inspect old local outputs privately.

For maintenance, recheck official MCP/CLI alternatives and the native docs, review a fresh OpenAPI checksum, run source-input comparison and matched fixtures, regenerate runtime/docs/CMS input tables, align root/lock/manifest/tag, scan public source/artifacts, run platform CI and verify actual anonymous install/desktop/read-only/client/CMS rendering. Never execute downloaded vendor code as a schema updater or infer provider success from a metadata hash.

Updates and removal

npm install -g @thenavidm/brandfetch-mcp-cli@latest
brandfetch-cli --version
npm uninstall -g @thenavidm/brandfetch-mcp-cli
codex mcp remove brandfetch

npx @latest resolves on process startup; reconnect/restart for updates. Global npm and desktop archives require explicit updates. Install the new versioned .mcpb and confirm its reported version. Remove client entries/extensions and revoke the provider key separately when access should end. Removal does not delete private files, undo crawls or revoke application client IDs.

Validation and remaining evidence

Typecheck/build, 47 behavior/shared-CLI tests, actual full/read-only stdio discovery and thirteen real CLI process fixtures pass. Every invalid/unconfigured/refused CLI case makes zero provider requests; HTTP error cases make exactly one injected request. Native schema maintenance verifies the pinned source/checksum without executing downloaded vendor code. Source/npm/desktop secret scans and production dependency audit report zero findings. Codex CLI0.159.3 accepts the documented registration in an isolated credential-free configuration.

Actual public artifacts, platform CI and saved/live CMS checks are recorded in the maintained release proof. Provider account outcomes, desktop GUI installation, fresh matched successful Codex task/token usage and the private site scene/shared installation helper deployment remain separately pending. No blanket superiority or measured token saving is claimed.