Nexus
About
Web search server that integrates Perplexity Sonar models via OpenRouter API for real-time, context-aware search with citations
Details
- Author
- adawalli
- Categories
- Search, Community, Other
Jump to
Setup
Install Nexus in your MCP client (Claude Desktop, Cursor, Windsurf, and others).
Repository: https://github.com/adawalli/nexus
Follow the installation instructions in the repository README, then restart your MCP client.
Intelligent AI model search and discovery with zero-install simplicity
Quick Start•Features•Documentation•Contributing
Nexus is aModel Context Protocol (MCP) serverthat provides AI-powered search functionality through the OpenRouter API. It integrates with MCP-compatible clients including Claude Desktop and Cursor, providing search capabilities via multiple model families including Perplexity Sonar (real-time web search) and Grok 4 (training-data knowledge).
- Zero-install deployment: Executable viabunx(ornpx) with no build requirements
- OpenRouter integration: Multiple AI models including Perplexity Sonar (web search) and Grok 4 (training data)
- MCP protocol compliance: Implements standard MCP tool and resource interfaces
- Production architecture: Includes request caching, deduplication, retry logic, and error handling
- Type-safe implementation: Full TypeScript coverage with strict type checking
- Bunx/NPX-based execution with zero local installation
- Cross-platform compatibility (macOS, Linux, Windows)
- Bun 1.0+ or Node.js 18+ runtime requirement
- Automated version updates via npm registry
- Multiple model tierswith different capabilities:
- sonar- Fast Q&A, real-time web search (30s timeout, standard tier)
- sonar-pro- Multi-step queries, real-time web search (60s timeout, premium tier)
- sonar-reasoning-pro- Chain-of-thought reasoning, real-time web search (120s timeout, premium tier)
- sonar-deep-research- Exhaustive research reports, real-time web search (300s timeout, premium tier)
- grok-4- Training-data knowledge, no real-time search (60s timeout, premium tier)
- Comprehensive error handling with typed error classes
- Request caching with configurable TTL
- Request deduplication for concurrent identical queries
- Automatic retry logic with exponential backoff
- Winston-based structured logging
- TypeScript strict mode implementation with full type coverage
- Bun1.0+ (recommended) or Node.js 18+
- OpenRouter API key (register at openrouter.ai)
Execute the server without local installation:
# Set your OpenRouter API key export OPENROUTER_API_KEY=your-api-key-here # Run the server via bunx (recommended) bunx nexus-mcp # Or via npx npx nexus-mcp
The server starts and listens for MCP client connections via STDIO transport.
# Test the CLI help bunx nexus-mcp --help # Test the version bunx nexus-mcp --version # Run with your API key OPENROUTER_API_KEY=your-key bunx nexus-mcp
Alternative: Local Development Installation
git clone https://github.com/adawalli/nexus.git cd nexus
# Copy the example environment file cp .env.example .env # Edit .env and add your actual API key # OPENROUTER_API_KEY=your-api-key-here
Configure MCP clients to execute the server via bunx:
Configuration in~/.claude/mcp_settings.json:
{ "mcpServers": { "nexus": { "command": "bunx", "args": ["nexus-mcp"], "env": { "OPENROUTER_API_KEY": "your-api-key-here" } } } }
Restart Claude Code after configuration changes.
Add server configuration in Cursor's MCP settings:
- Name:nexus
- Command:bunx
- Args:["nexus-mcp"]
- Environment Variables:OPENROUTER_API_KEY=your-api-key-here
Restart Cursor after configuration changes.
Standard MCP client connection parameters:
- Transport: stdio
- Command:bunx
- Args:["nexus-mcp"]
- Environment:OPENROUTER_API_KEY=your-api-key-here
If you don't have Bun installed, usenpxin place ofbunxin any of the configurations above.
For a local installation (after following the local development setup):
{ "mcpServers": { "nexus": { "command": "bun", "args": ["run", "/path/to/nexus-mcp/dist/cli.js"], "env": { "OPENROUTER_API_KEY": "your-api-key-here" } } } }
Once integrated, you can use the search tool in your MCP client:
Use the search tool to find information about "latest developments in AI"
Search for "climate change solutions" using: - Model: sonar-pro - Max tokens: 2000 - Temperature: 0.3
# Fast Q&A with real-time web search (default) Search for "latest news" with model: sonar # Deep research with comprehensive analysis Search for "AI safety research" with model: sonar-deep-research # Knowledge from training data (no web search) Search for "explain quantum computing" with model: grok-4
The main search tool that provides AI-powered search capabilities.
- query(required): Search query (1-2000 characters)
- model(optional): Model to use (default:sonar)
- sonar- Fast Q&A with real-time web search (30s timeout)
- sonar-pro- Multi-step queries with real-time web search (60s timeout, premium)
- sonar-reasoning-pro- Chain-of-thought reasoning with real-time web search (120s timeout, premium)
- sonar-deep-research- Exhaustive research reports with real-time web search (300s timeout, premium)
- grok-4- Training-data knowledge, no real-time search (60s timeout, premium)
Based on current information, here are the latest developments in AI... [Detailed AI-generated response with current information] --- Search Metadata: - Model: perplexity/sonar - Response time: 1250ms - Tokens used: 850 - Timeout: 30000ms - Search type: realtime - Sources: 5 found
Quantum computing is a type of computation that harnesses quantum mechanics... [Response based on training data knowledge] --- Search Metadata: - Model: x-ai/grok-4 - Response time: 3500ms - Tokens used: 650 - Timeout: 60000ms - Search type: training-data - Cost tier: premium
- OPENROUTER_API_KEY(required): Your OpenRouter API key
- NODE_ENV(optional): Environment setting (development, production, test)
- LOG_LEVEL(optional): Logging level (debug, info, warn, error)
The server supports additional configuration through environment variables:
- OPENROUTER_TIMEOUT_MS: Request timeout in milliseconds (default: 30000)
- OPENROUTER_MAX_RETRIES: Maximum retry attempts (default: 3)
- OPENROUTER_BASE_URL: Custom OpenRouter API base URL
The server provides a configuration status resource atconfig://statusthat shows:
- Server health status
- Configuration information (with masked API key)
- Search tool availability
- Server uptime and version
- Install Bun:curl -fsSL https://bun.sh/install | bash
- Or fall back to npx if you have Node.js 18+ installed
- Ensure Node.js 18+ is installed:node --version
- Update npm:npm install -g npm@latest
"Cannot find package 'nexus-mcp'"
- The package may not be published yet. Use local installation instead
- Verify network connectivity for npm registry access
- This is normal on first run as the package is downloaded
- Subsequent runs will be faster due to caching
- For faster startup, use local installation instead
"Permission denied" errors with npx
- Try:npx --yes nexus-mcp --stdio
- Or set npm permissions:npm config set user 0 && npm config set unsafe-perm true
"Search functionality is not available"
- EnsureOPENROUTER_API_KEYenvironment variable is set
- Verify your API key is valid atOpenRouter
- Check the server logs for initialization errors
"Authentication failed: Invalid API key"
- Double-check your API key format and validity
- Ensure the key has sufficient credits/permissions
- Test the key directly at OpenRouter dashboard
- Wait for the rate limit to reset (usually 1 minute)
- Consider upgrading your OpenRouter plan for higher limits
- Monitor usage in your OpenRouter dashboard
- Check your internet connection
- The server will automatically retry failed requests
- Increase timeout if needed:OPENROUTER_TIMEOUT_MS=60000
- Verify your MCP configuration uses the correct command and arguments
- Check that Bun 1.0+ or Node.js 18+ is available in your MCP client's environment
- Ensure the API key is properly set in the environment variables
For local development:AddLOG_LEVEL=debugto your.envfile
For MCP clients:AddLOG_LEVEL: "debug"to theenvsection of your MCP configuration
This will provide detailed information about:
- Configuration loading
- API requests and responses
- Error details and stack traces
- Performance metrics
You can test if the server is working by checking the configuration status resource in your MCP client, or by running a simple search query.
# Development with hot reload bun run dev # Run tests bun run test # Run tests with coverage bun run test:coverage # Lint code bun run lint # Format code bun run format
OpenRouter charges for API usage based on token consumption:
- Pricing: See current rates atOpenRouter Models
- Monitoring: Usage tracking available in OpenRouter dashboard
- Limits: Configure spending limits in OpenRouter account settings
- Optimization: Server implements response caching and request deduplication to minimize redundant API calls
We welcome contributions from developers of all experience levels!
- Fork the repository
- Read ourContributing Guide
- Check outgood first issues
- Bug Reports
- Feature Requests
- Ask Questions
- GitHub Discussions
- Code of Conduct
- Roadmap & Project Board
- Model Context Protocol- The standard we implement
- OpenRouter- Our AI model provider
- Claude Desktop- Primary MCP client
- Cursor- AI-powered code editor with MCP support
MIT License- seeLICENSEfile for details.
Made with ❤️ by the open source community
⭐ Star us on GitHub•📦 View on NPM•📚 Read the Docs
Nexus: AI integration without the complexity
Search global news using natural language. Webz.io News Search API returns the most relevant articles and content, with filters for source, country, language, date, sentiment, and category.
Search for IP addresses using Chaitin's IP Intelligence API.
Get any answer from the Facebook Ads Library, conduct deep research including messaging, creative testing and comparisons in seconds.
Google News search capabilities with automatic topic categorization and multi-language support via SerpAPI integration.
A Model Context Protocol (MCP) server providing access to Google Programmable Search Engine (PSE) and Custom Search Engine (CSE).
A Model Context Protocol (MCP) server providing access to Google Search Console.
A Model Context Protocol (MCP) server for the Open Library API that enables AI assistants to search for book and author information.
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
