MCP Deep Search

# MCP Deep Search [](https://www.npmjs.com/package/@just-every/mcp-deep-search) [](https://opensource.org/licenses/MIT) MCP 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. ## Quick Start ### 1. Create or use an environment file Option A: Create a new `.llm.env` file in your home directory: ```bash # Download example env file curl -o ~/.llm.env https://raw.githubusercontent.com/just-every/mcp-deep-search/main/.env.example # Edit with your API keys nano ~/.llm.env ``` Option B: Use an existing `.env` file (must use absolute path): ```bash # Example: /Users/yourname/projects/myproject/.env # Example: /home/yourname/workspace/.env ``` ### 2. Install #### Claude Code ```bash # Using ~/.llm.env claude mcp add deep-search -s user -e ENV_FILE=$HOME/.llm.env -- npx -y @just-every/mcp-deep-search # Using existing .env file (absolute path required) claude mcp add deep-search -s user -e ENV_FILE=/absolute/path/to/your/.env -- npx -y @just-every/mcp-deep-search # For debugging, check if ENV_FILE is being passed correctly: claude mcp list ``` #### Other MCP Clients Add to your MCP configuration: ```json { "mcpServers": { "deep-search": { "command": "npx", "args": ["-y", "@just-every/mcp-deep-search"], "env": { "ENV_FILE": "/path/to/.llm.env" } } } } ``` ## MCP Tools ### `deep_search` Perform web searches using a specific provider. **Parameters:** - `query` (required): The search query - `provider`: Search provider (default: brave) - `maxResults`: Maximum results (default: 10) - `includeAnswer`: Include AI answer if available (default: false) ### `comprehensive_research` Perform comprehensive research using AI agents that intelligently select and query multiple search engines. **Parameters:** - `query` (required): The research topic - `modelClass`: AI model class (default: reasoning_mini) ## Search Providers | Provider | API Key Required | Description | |----------|-----------------|-------------| | `brave` | `BRAVE_API_KEY` | Privacy-first search with structured results | | `anthropic` | `ANTHROPIC_API_KEY` | Deep multi-hop research | | `openai` | `OPENAI_API_KEY` | ChatGPT-grade contextual search | | `google` | `GOOGLE_API_KEY` | Gemini grounding search | | `sonar` / `sonar-pro` | `OPENROUTER_API_KEY` | Perplexity search variants | | `xai` | `XAI_API_KEY` | Real-time Grok search | ## CLI Usage ```bash # Basic search mcp-deep-search search "your query" # Search with specific provider mcp-deep-search search "your query" -p brave # Get more results mcp-deep-search search "your query" -n 20 ``` ## Troubleshooting ### MCP Server Shows "Failed" in Claude If you see "deep-search ✘ failed" in Claude, check these common issues: 1. **Missing API Keys**: The most common issue is missing API keys. Check that your ENV_FILE is properly configured: ```bash # Test if ENV_FILE is working ENV_FILE=/path/to/your/.env npx @just-every/mcp-deep-search search "test" ``` 2. **Incorrect Installation Command**: Make sure you're using `-e` for environment variables: ```bash # Correct - environment variable passed with -e flag before -- claude mcp add deep-search -s user -e ENV_FILE=$HOME/.llm.env -- npx -y @just-every/mcp-deep-search # Incorrect - trying to pass as argument claude mcp add deep-search -s user -- npx -y @just-every/mcp-deep-search --env ENV_FILE=$HOME/.llm.env ``` 3. **Path Issues**: ENV_FILE must use absolute paths: ```bash # Good ENV_FILE=/Users/yourname/.llm.env ENV_FILE=$HOME/.llm.env # Bad ENV_FILE=.env ENV_FILE=~/.llm.env # ~ not expanded in some contexts ``` 4. **Verify Installation**: Check your MCP configuration: ```bash claude mcp list ``` 5. **Debug Mode**: For detailed error messages, run manually: ```bash ENV_FILE=/path/to/.env npx @just-every/mcp-deep-search ``` ## Getting API Keys - **Brave**: [brave.com/search/api](https://brave.com/search/api/) - **Anthropic**: [console.anthropic.com](https://console.anthropic.com/) - **OpenAI**: [platform.openai.com](https://platform.openai.com/) - **Google**: [makersuite.google.com](https://makersuite.google.com/) - **OpenRouter**: [openrouter.ai](https://openrouter.ai/) - **xAI**: [x.ai](https://x.ai/) ## Auto-Restart Feature The MCP server includes automatic restart capability by default for improved reliability: - Automatically restarts the server if it crashes - Handles unhandled exceptions and promise rejections - Implements exponential backoff (max 10 attempts in 1 minute) - Logs all restart attempts for monitoring - Gracefully handles shutdown signals (SIGINT, SIGTERM) For development/debugging without auto-restart: ```bash # Run directly without restart wrapper npm run serve:dev ``` ## License MIT © Just Every