CherryHQ/cherry-studio · critical · Error

BRAVE_API_KEY is required for Brave Search MCP server

Error message

BRAVE_API_KEY is required for Brave Search MCP server

What it means

Constructor guard on BraveSearchServer: if the apiKey argument is empty/undefined, it refuses to construct. The factory at factory.ts:32 passes envs.BRAVE_API_KEY, so a missing or empty env var triggers this at server-creation time, before any tool call.

Source

Thrown at src/main/ai/mcp/servers/braveSearch.ts:297

Address: ${address}
Phone: ${poi.phone || 'N/A'}
Rating: ${poi.rating?.ratingValue ?? 'N/A'} (${poi.rating?.ratingCount ?? 0} reviews)
Price Range: ${poi.priceRange || 'N/A'}
Hours: ${(poi.openingHours || []).join(', ') || 'N/A'}
Description: ${descData.descriptions[poi.id] || 'No description available'}
`
      })
      .join('\n---\n') || 'No local results found'
  )
}

class BraveSearchServer {
  public server: Server
  private apiKey: string

  constructor(apiKey: string) {
    if (!apiKey) {
      throw new Error('BRAVE_API_KEY is required for Brave Search MCP server')
    }
    this.apiKey = apiKey
    this.server = new Server(
      {
        name: 'brave-search-server',
        version: '0.1.0'
      },
      {
        capabilities: {
          tools: {}
        }
      }
    )
    this.initialize()
  }

  initialize() {
    // Tool handlers

View on GitHub (pinned to 726446b54c)

Solutions

  1. Obtain a Brave Search API subscription token from https://brave.com/search/api/.
  2. In the MCP server configuration, set the BRAVE_API_KEY env var to that token (the factory reads envs.BRAVE_API_KEY).
  3. Restart/reload the MCP server after saving so the factory re-instantiates BraveSearchServer.
  4. Verify the key has no surrounding whitespace or quotes.

Example fix

// before — server config missing the key
// envs: {}

// after — provide the key in the server's env config
// envs: { "BRAVE_API_KEY": "BSA<your-token>" }
Defensive patterns

Strategy: validation

Validate before calling

// Validate the key before enabling the Brave Search server
function validateBraveKey(envs: Record<string, string>) {
  const key = envs.BRAVE_API_KEY
  if (typeof key !== 'string' || !key.trim()) {
    throw new Error('BRAVE_API_KEY env var is required to enable the Brave Search MCP server')
  }
  if (!/^BSA[A-Za-z0-9]+$/.test(key.trim())) {
    throw new Error('BRAVE_API_KEY does not look like a Brave Search token')
  }
  return key.trim()
}

Type guard

function hasBraveKey(envs: unknown): envs is { BRAVE_API_KEY: string } {
  return typeof envs === 'object' && envs !== null && typeof (envs as any).BRAVE_API_KEY === 'string' && (envs as any).BRAVE_API_KEY.trim().length > 0
}

Try / catch

try {
  server = new BraveSearchServer(validateBraveKey(envs)).server
} catch (e) {
  logger.error('Brave Search server disabled', { error: e.message })
  // surface to UI: prompt user to set BRAVE_API_KEY
}

Prevention

When it happens

Trigger: User enabled the Brave Search MCP server in settings but did not supply a BRAVE_API_KEY env var, or supplied an empty string. The in-memory MCP factory is invoked and BraveSearchServer construction throws synchronously.

Common situations: MCP server config UI saved without the key; key field named incorrectly (e.g. API_KEY instead of BRAVE_API_KEY); env var unset in the launched environment; user expected a trial key to be preconfigured.

Related errors

AI-assisted analysis of CherryHQ/cherry-studio@726446b54c (2026-08-12). Data as JSON: /api/errors/51dcc746f1039f5f. Report an issue: GitHub.