# adawalli/nexus [Health: Active] **Category:** 🔎 Search & Data Extraction **Repository:** https://github.com/adawalli/nexus **GitHub Stars:** 23 **npm Downloads (last month):** 5137 **Views:** 2 **Installs:** 0 **Upvotes:** 0 **Directory Page:** https://allmcps.com/mcp/adawalli-nexus ## Description AI-powered web search server using Perplexity Sonar models with source citations. Zero-install setup via NPX. ## Tools Capabilities this server exposes over MCP: - **search** — The main search tool that provides AI-powered search capabilities. ## Claude Desktop Quick Installation Install path detected from listing signals. Uses `bunx` (confidence: high): ```json "mcpServers": { "nexus": { "command": "bunx", "args": ["nexus-mcp"], "env": { "OPENROUTER_API_KEY": "" } } } ``` **Requires environment variables:** `OPENROUTER_API_KEY` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for). ## Documentation & README
# 🔍 Nexus MCP Server **AI integration without the complexity** [![npm version](https://img.shields.io/npm/v/nexus-mcp.svg)](https://www.npmjs.com/package/nexus-mcp) ![NPM Downloads](https://img.shields.io/npm/dt/nexus-mcp?style=flat-square&logo=npm&label=downloads) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/) [![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io/) [![CodeRabbit Pull Request Reviews](https://img.shields.io/coderabbit/prs/github/adawalli/nexus)](https://coderabbit.ai) [![Trust Score](https://archestra.ai/mcp-catalog/api/badge/quality/adawalli/nexus)](https://archestra.ai/mcp-catalog/adawalli__nexus) _Intelligent AI model search and discovery with zero-install simplicity_ [Quick Start](#-quick-start) • [Features](#-features) • [Documentation](#-documentation) • [Contributing](#-contributing)
--- ## What is Nexus? Nexus is a **Model Context Protocol (MCP) server** that 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). ### Key Characteristics - **Zero-install deployment**: Executable via `bunx` (or `npx`) 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 ## Features ### Deployment - 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 ### Search Capabilities - **Multiple model tiers** with 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) - Real-time web search with current information (Perplexity models) - Training-data knowledge responses (Grok 4) - Structured citation extraction from responses - Configurable model parameters (temperature, max tokens, timeout override) ### Architecture - 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 ## Quick Start ### Prerequisites - [Bun](https://bun.sh) 1.0+ (recommended) or Node.js 18+ - OpenRouter API key ([register at openrouter.ai](https://openrouter.ai)) ### Quick Install Execute the server without local installation: ```bash # 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. ### Testing the Installation ```bash # 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 For local development or customization: 1. Clone the repository: ```bash git clone https://github.com/adawalli/nexus.git cd nexus ``` 2. Install dependencies: ```bash bun install ``` 3. Build the server: ```bash bun run build ``` 4. Configure your OpenRouter API key: ```bash # Copy the example environment file cp .env.example .env # Edit .env and add your actual API key # OPENROUTER_API_KEY=your-api-key-here ``` 5. Test the server: ```bash bun run start ``` ## Integration with MCP Clients ### Bunx-Based Integration (Recommended) Configure MCP clients to execute the server via bunx: ### Claude Code Configuration in `~/.claude/mcp_settings.json`: ```json { "mcpServers": { "nexus": { "command": "bunx", "args": ["nexus-mcp"], "env": { "OPENROUTER_API_KEY": "your-api-key-here" } } } } ``` Restart Claude Code after configuration changes. ### Cursor 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. ### Generic MCP Client Configuration Standard MCP client connection parameters: - **Transport**: stdio - **Command**: `bunx` - **Args**: `["nexus-mcp"]` - **Environment**: `OPENROUTER_API_KEY=your-api-key-here` ### Alternative: npx or Local Installation If you don't have Bun installed, use `npx` in place of `bunx` in any of the configurations above. For a local installation (after following the local development setup): ```json { "mcpServers": { "nexus": { "command": "bun", "args": ["run", "/path/to/nexus-mcp/dist/cli.js"], "env": { "OPENROUTER_API_KEY": "your-api-key-here" } } } } ``` ## Usage Once integrated, you can use the search tool in your MCP client: ### Basic Search ``` Use the search tool to find information about "latest developments in AI" ``` ### Advanced Search with Parameters ``` Search for "climate change solutions" using: - Model: sonar-pro - Max tokens: 2000 - Temperature: 0.3 ``` ### Using Different Models ``` # 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 ``` ## Available Tools ### `search` The main search tool that provides AI-powered search capabilities. **Parameters:** - `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) - `maxTokens` (optional): Maximum response tokens (1-4000, default: 1000) - `temperature` (optional): Response randomness (0-2, default: 0.3) - `timeout` (optional): Override default timeout in milliseconds (5000-600000) **Example Response (Perplexity model):** ``` 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 ``` **Example Response (Grok 4 model):** ``` 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 ``` ## Configuration ### Environment Variables - `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) ### Advanced Configuration 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 ## Resources The server provides a configuration status resource at `config://status` that shows: - Server health status - Configuration information (with masked API key) - Search tool availability - Server uptime and version ## Troubleshooting ### Bunx/NPX-Specific Issues **"bunx: command not found"** - Install Bun: `curl -fsSL https://bun.sh/install | bash` - Or fall back to npx if you have Node.js 18+ installed **"npx: command not found"** - 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 **Slow startup on first run** - 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` ### Common Issues **"Search functionality is not available"** - Ensure `OPENROUTER_API_KEY` environment variable is set - Verify your API key is valid at [OpenRouter](https://openrouter.ai) - 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 **"Rate limit exceeded"** - Wait for the rate limit to reset (usually 1 minute) - Consider upgrading your OpenRouter plan for higher limits - Monitor usage in your OpenRouter dashboard **Connection timeouts** - Check your internet connection - The server will automatically retry failed requests - Increase timeout if needed: `OPENROUTER_TIMEOUT_MS=60000` **MCP client can't connect to server** - 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 ### Debug Logging Enable debug logging by: **For local development:** Add `LOG_LEVEL=debug` to your `.env` file **For MCP clients:** Add `LOG_LEVEL: "debug"` to the `env` section of your MCP configuration This will provide detailed information about: - Configuration loading - API requests and responses - Error details and stack traces - Performance metrics ### Testing Connection 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 For developers working on this server: ```bash # 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 ``` ## API Costs OpenRouter charges for API usage based on token consumption: - **Pricing**: See current rates at [OpenRouter Models](https://openrouter.ai/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 ## 📚 Documentation
| 📖 **Guide** | 🔗 **Link** | 📝 **Description** | | ------------------- | ------------------------------------------- | -------------------------------- | | **Quick Start** | [Getting Started](#-quick-start) | Zero-install setup in 30 seconds | | **API Reference** | [MCP Tools](https://github.com/adawalli/nexus/blob/HEAD/CLAUDE.md#development-commands) | Complete command reference | | **Configuration** | [Environment Setup](#configuration) | Advanced configuration options | | **Contributing** | [Contributing Guide](https://github.com/adawalli/nexus/blob/HEAD/CONTRIBUTING.md) | Join our open source community | | **Troubleshooting** | [Common Issues](#troubleshooting) | Solutions to common problems |
## 🤝 Contributing We welcome contributions from developers of all experience levels!
### 🚀 **Get Started** - Fork the repository - Read our [Contributing Guide](https://github.com/adawalli/nexus/blob/HEAD/CONTRIBUTING.md) - Check out [good first issues](https://github.com/search?q=repo%3Anexus-mcp+label%3A%22good+first+issue%22&type=issues) ### 🐛 **Report Issues** - [Bug Reports](https://github.com/adawalli/nexus/issues/new) - [Feature Requests](https://github.com/adawalli/nexus/issues/new) - [Ask Questions](https://github.com/adawalli/nexus/issues/new) ### 💬 **Join Community** - [GitHub Discussions](https://github.com/adawalli/nexus/discussions) - [Code of Conduct](https://github.com/adawalli/nexus/blob/HEAD/CODE_OF_CONDUCT.md) - [Roadmap & Project Board](https://github.com/adawalli/nexus/projects)
### 🌟 Recognition Contributors are recognized in our: - [Contributors list](https://github.com/adawalli/nexus/graphs/contributors) - Release notes for significant contributions - Community spotlights and testimonials ## 🔗 Related Projects - [Model Context Protocol](https://modelcontextprotocol.io) - The standard we implement - [OpenRouter](https://openrouter.ai) - Our AI model provider - [Claude Desktop](https://claude.ai) - Primary MCP client - [Cursor](https://cursor.sh) - AI-powered code editor with MCP support ## 📞 Support & Community
| 💬 **Need Help?** | 🔗 **Resource** | | -------------------- | ---------------------------------------------------------------------------------------------------- | | **Quick Questions** | [GitHub Discussions](https://github.com/adawalli/nexus/discussions) | | **Bug Reports** | [GitHub Issues](https://github.com/adawalli/nexus/issues) | | **Documentation** | [OpenRouter Docs](https://openrouter.ai/docs) • [MCP Specification](https://modelcontextprotocol.io) | | **Feature Requests** | [Enhancement Proposals](https://github.com/adawalli/nexus/issues/new) |
## 📄 License **MIT License** - see [LICENSE](https://github.com/adawalli/nexus/blob/HEAD/LICENSE) file for details. ---
**Made with ❤️ by the open source community** [⭐ Star us on GitHub](https://github.com/adawalli/nexus) • [📦 View on NPM](https://www.npmjs.com/package/nexus-mcp) • [📚 Read the Docs](https://github.com/adawalli/nexus/blob/HEAD/CLAUDE.md) _Nexus: AI integration without the complexity_ [![Star History Chart](https://api.star-history.com/svg?repos=adawalli/nexus&type=Date)](https://star-history.com/#adawalli/nexus&Date)