{"id":"228a2a3f-54de-4313-98a6-4f59c2334e76","slug":"mcp-deep-search","kind":"mcp","name":"mcp-deep-search","summary":"Runs a search across all major providers simultaneously","owner":"just-every","repoUrl":"https://github.com/just-every/mcp-deep-search","license":"MIT","licenseTier":"permissive","trust":"community","stars":9,"match":null,"fewStars":false,"format":"mcp","createdAt":"2025-06-12T12:09:45.000Z","addedAt":"2026-10-14T05:09:21.984Z","logoUrl":"https://avatars.githubusercontent.com/u/213184375?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["search","cloud-infra"],"tags":["agent","llm","search","web-search"],"runtime":"node","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-17T07:44:19.139Z","sample":false,"url":"https://conduits.dev/tools/mcp-deep-search","language":"TypeScript","transports":["stdio"],"install":{"npm":"@just-every/mcp-deep-search"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# MCP Deep Search\n\n[![npm version](https://badge.fury.io/js/%40just-every%2Fmcp-deep-search.svg)](https://www.npmjs.com/package/@just-every/mcp-deep-search)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nMCP server for deep web search using [@just-every/search](https://github.com/just-every/search). Search across multiple providers including Google, Bing, Brave, DuckDuckGo, Perplexity, and more.\n\n## Quick Start\n\n### 1. Create or use an environment file\n\nOption A: Create a new `.llm.env` file in your home directory:\n```bash\n# Download example env file\ncurl -o ~/.llm.env https://raw.githubusercontent.com/just-every/mcp-deep-search/main/.env.example\n\n# Edit with your API keys\nnano ~/.llm.env\n```\n\nOption B: Use an existing `.env` file (must use absolute path):\n```bash\n# Example: /Users/yourname/projects/myproject/.env\n# Example: /home/yourname/workspace/.env\n```\n\n### 2. Install\n\n#### Claude Code\n```bash\n# Using ~/.llm.env\nclaude mcp add deep-search -s user -e ENV_FILE=$HOME/.llm.env -- npx -y @just-every/mcp-deep-search\n\n# Using existing .env file (absolute path required)\nclaude mcp add deep-search -s user -e ENV_FILE=/absolute/path/to/your/.env -- npx -y @just-every/mcp-deep-search\n\n# For debugging, check if ENV_FILE is being passed correctly:\nclaude mcp list\n```\n\n#### Other MCP Clients\nAdd to your MCP configuration:\n```json\n{\n  \"mcpServers\": {\n    \"deep-search\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@just-every/mcp-deep-search\"],\n      \"env\": {\n        \"ENV_FILE\": \"/path/to/.llm.env\"\n      }\n    }\n  }\n}\n```\n\n## MCP Tools\n\n### `deep_search`\nPerform web searches using a specific provider.\n\n**Parameters:**\n- `query` (required): The search query\n- `provider`: Search provider (default: brave)\n- `maxResults`: Maximum results (default: 10)\n- `includeAnswer`: Include AI answer if available (default: false)\n\n### `comprehensive_research`\nPerform comprehensive research using AI agents that intelligently select and query multiple search engines.\n\n**Parameters:**\n- `query` (required): The research topic\n- `modelClass`: AI model class (default: reasoning_mini)\n\n## Search Providers\n\n| Provider | API Key Required | Description |\n|----------|-----------------|-------------|\n| `brave` | `BRAVE_API_KEY` | Privacy-first search with structured results |\n| `anthropic` | `ANTHROPIC_API_KEY` | Deep multi-hop research |\n| `openai` | `OPENAI_API_KEY` | ChatGPT-grade contextual search |\n| `google` | `GOOGLE_API_KEY` | Gemini grounding search |\n| `sonar` / `sonar-pro` | `OPENROUTER_API_KEY` | Perplexity search variants |\n| `xai` | `XAI_API_KEY` | Real-time Grok search |\n\n## CLI Usage\n\n```bash\n# Basic search\nmcp-deep-search search \"your query\"\n\n# Search with specific provider\nmcp-deep-search search \"your query\" -p brave\n\n# Get more results\nmcp-deep-search search \"your query\" -n 20\n```\n\n## Troubleshooting\n\n### MCP Server Shows \"Failed\" in Claude\n\nIf you see \"deep-search ✘ failed\" in Claude, check these common issues:\n\n1. **Missing API Keys**: The most common issue is missing API keys. Check that your ENV_FILE is properly configured:\n   ```bash\n   # Test if ENV_FILE is working\n   ENV_FILE=/path/to/your/.env npx @just-every/mcp-deep-search search \"test\"\n   ```\n\n2. **Incorrect Installation Command**: Make sure you're using `-e` for environment variables:\n   ```bash\n   # Correct - environment variable passed with -e flag before --\n   claude mcp add deep-search -s user -e ENV_FILE=$HOME/.llm.env -- npx -y @just-every/mcp-deep-search\n   \n   # Incorrect - trying to pass as argument\n   claude mcp add deep-search -s user -- npx -y @just-every/mcp-deep-search --env ENV_FILE=$HOME/.llm.env\n   ```\n\n3. **Path Issues**: ENV_FILE must use absolute paths:\n   ```bash\n   # Good\n   ENV_FILE=/Users/yourname/.llm.env\n   ENV_FILE=$HOME/.llm.env\n   \n   # Bad\n   ENV_FILE=.env\n   ENV_FILE=~/.llm.env  # ~ not expanded in some contexts\n   ```\n\n4. **Verify Installation**: Check your MCP configuration:\n   ```bash\n   claude mcp list\n   ```\n\n5. **Debug Mode**: For detailed error messages, run manually:\n   ```bash\n   ENV_FILE=/path/to/.env npx @just-every/mcp-deep-search\n   ```\n\n## Getting API Keys\n\n- **Brave**: [brave.com/search/api](https://brave.com/search/api/)\n- **Anthropic**: [console.anthropic.com](https://console.anthropic.com/)\n- **OpenAI**: [platform.openai.com](https://platform.openai.com/)\n- **Google**: [makersuite.google.com](https://makersuite.google.com/)\n- **OpenRouter**: [openrouter.ai](https://openrouter.ai/)\n- **xAI**: [x.ai](https://x.ai/)\n\n## Auto-Restart Feature\n\nThe MCP server includes automatic restart capability by default for improved reliability:\n\n- Automatically restarts the server if it crashes\n- Handles unhandled exceptions and promise rejections\n- Implements exponential backoff (max 10 attempts in 1 minute)\n- Logs all restart attempts for monitoring\n- Gracefully handles shutdown signals (SIGINT, SIGTERM)\n\nFor development/debugging without auto-restart:\n```bash\n# Run directly without restart wrapper\nnpm run serve:dev\n```\n\n## License\n\nMIT © Just Every"}