# 🔍 Nexus MCP Server
**AI integration without the complexity**
[](https://www.npmjs.com/package/nexus-mcp)
[](https://opensource.org/licenses/MIT)
[](https://www.typescriptlang.org/)
[](https://modelcontextprotocol.io/)
[](https://coderabbit.ai)
[](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](CLAUDE.md#development-commands) | Complete command reference |
| **Configuration** | [Environment Setup](#configuration) | Advanced configuration options |
| **Contributing** | [Contributing Guide](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](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](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](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](CLAUDE.md)
_Nexus: AI integration without the complexity_
[](https://star-history.com/#adawalli/nexus&Date)