Earch MCP

The Universal MCP Server exposes tools for your workflows and is designed for prompt-first usage in MCP-compatible clients.

Installation

Prerequisites

• Node.js 18+

• Set EARCH_MCP_API_KEY in your environment (or BRAVE_API_KEY)

Get an API key

• If your tools require an external API, obtain a key from the provider’s docs/console.

• Otherwise, you can skip this step.

Build locally

Setup: Claude Code (CLI)

Use this one-liner (replace with your real values):

To remove:

Setup: Cursor

Create .cursor/mcp.json in your client (do not commit it here):

Other Clients and Agents

Install via URI or CLI:

Follow the MCP install guide and reuse the standard config above.

• Command: npx

• Args: ["earch-mcp"]

• Env: EARCH_MCP_API_KEY=sk-your-real-key

• Type: STDIO

• Command: npx

• Args: earch-mcp

• Enabled: true

Example ~/.config/opencode/opencode.json:

Add a new MCP and paste the standard JSON config.

See docs and reuse the standard config above.

Setup: Codex (TOML)

Example (Serena):

This server (minimal):

Configuration (Env)

• EARCH_MCP_API_KEY: Your API key (or BRAVE_API_KEY)

• MCP_NAME: Server name override (default: earch-mcp)

Available Tools

• web.search

  • inputs: { q: string, count?: number (<=50), country?: string, safesearch?: "off"|"moderate"|"strict", freshness?: "pd"|"pw"|"pm"|"py" }

  • outputs: JSON from Brave Web Search API

• local.pois

  • inputs: { ids: string[1..20] }

  • outputs: JSON from Brave Local POIs API

• local.descriptions

  • inputs: { ids: string[1..20] }

  • outputs: JSON from Brave Local Descriptions API

• web.rich

  • inputs: { q: string }

  • outputs: JSON containing hint and rich callback result

Example invocation (MCP tool call)

Troubleshooting

• 401 auth errors: check EARCH_MCP_API_KEY or BRAVE_API_KEY

• Ensure Node 18+

• Local runs: npx earch-mcp after npm run build

• Inspect publish artifacts: npm pack --dry-run

References

• MCP SDK: https://modelcontextprotocol.io/docs/sdks

• Architecture: https://modelcontextprotocol.io/docs/learn/architecture

• Server Concepts: https://modelcontextprotocol.io/docs/learn/server-concepts

• Server Spec: https://modelcontextprotocol.io/specification/2025-06-18/server/index

• Brave Search API: https://api.search.brave.com/res/v1/web/search

• Brave Local API: https://api.search.brave.com/res/v1/local/pois

• Brave Rich API: https://api.search.brave.com/res/v1/web/rich

Name Consistency & Troubleshooting

• Always use CANONICAL_ID (earch-mcp) for identifiers and keys.

• Use CANONICAL_DISPLAY (Earch MCP) only for UI labels.

• Do not mix legacy keys after registration.

Consistency Matrix:

• npm package name → earch-mcp

• Binary name → earch-mcp

• MCP server name (SDK metadata) → earch-mcp

• Env default MCP_NAME → earch-mcp

• Client registry key → earch-mcp

• UI label → Earch MCP

Conflict Cleanup:

• Remove any stale keys (e.g., old display names) and re-add with earch-mcp only.

• Cursor: configure in the UI; this project intentionally omits .cursor/mcp.json.