# 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
```bash
cd /path/to/earch-mcp
npm i
npm run build
```

## Setup: Claude Code (CLI)

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

```bash
claude mcp add Earch MCP -s user -e EARCH_MCP_API_KEY="sk-your-real-key" -- npx earch-mcp
```

To remove:

```bash
claude mcp remove Earch MCP
```

## Setup: Cursor

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

```json
{
  "mcpServers": {
    "earch-mcp": {
      "command": "npx",
      "args": ["earch-mcp"],
      "env": { "EARCH_MCP_API_KEY": "sk-your-real-key" },
      "autoStart": true
    }
  }
}
```

## Other Clients and Agents

<details>
<summary>VS Code</summary>

Install via URI or CLI:

```bash
code --add-mcp '{"name":"earch-mcp","command":"npx","args":["earch-mcp"],"env":{"EARCH_MCP_API_KEY":"sk-your-real-key"}}'
```

</details>

<details>
<summary>Claude Desktop</summary>

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

</details>

<details>
<summary>LM Studio</summary>

- Command: npx
- Args: ["earch-mcp"]
- Env: EARCH_MCP_API_KEY=sk-your-real-key

</details>

<details>
<summary>Goose</summary>

- Type: STDIO
- Command: npx
- Args: earch-mcp
- Enabled: true

</details>

<details>
<summary>opencode</summary>

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

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "earch-mcp": {
      "type": "local",
      "command": ["npx", "earch-mcp"],
      "enabled": true
    }
  }
}
```

</details>

<details>
<summary>Qodo Gen</summary>

Add a new MCP and paste the standard JSON config.

</details>

<details>
<summary>Windsurf</summary>

See docs and reuse the standard config above.

</details>

## Setup: Codex (TOML)

Example (Serena):

```toml
[mcp_servers.serena]
command = "uvx"
args = ["--from", "git+https://github.com/oraios/serena", "serena", "start-mcp-server", "--context", "codex"]
```

This server (minimal):

```toml
[mcp_servers.earch-mcp]
command = "npx"
args = ["earch-mcp"]
# Optional environment variables:
# EARCH_MCP_API_KEY = "sk-your-real-key"
# MCP_NAME = "earch-mcp"
```

## 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)

```json
{
  "tool": "web.search",
  "arguments": { "q": "brave search" }
}
```

## 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.