<!-- markdownlint-disable MD033 MD041 -->

<div align="center">

🔍 Nexus MCP Server

AI integration without the complexity

Intelligent AI model search and discovery with zero-install simplicity

Quick Start • Features • Documentation • Contributing

</div>

---

🚀 What is Nexus?

Nexus is a production-ready Model Context Protocol (MCP) server that brings AI-powered web search directly into your development environment. Get intelligent search results with proper citations in Claude Desktop, Cursor, or any MCP-compatible client - all with a single command.

Why Nexus?

• 🎯 Zero Setup: Ready in 30 seconds with npx - no installation, no configuration
• 🧠 AI-Powered: Uses Perplexity Sonar models for intelligent, current web search
• 📚 Source Citations: Get authoritative sources with every search result
• 🔧 Developer-First: Built for developers who want AI capabilities without complexity
• ⚡ Production-Ready: Enterprise-grade reliability with comprehensive error handling

✨ Features

<table> <tr> <td width="50%">

🚀 Zero-Install Simplicity

• Ready in 30 seconds with npx
• No dependencies or build steps
• Cross-platform compatibility
• Always up-to-date

🧠 AI-Powered Intelligence

• Perplexity Sonar model integration
• Real-time web content search
• Context-aware result ranking
• Multiple model options

</td> <td width="50%">

📚 Professional Quality

• Source citations and metadata
• Comprehensive error handling
• Production-grade reliability
• TypeScript implementation

🔧 Developer Experience

• MCP protocol compliance
• Extensive documentation
• Configurable parameters
• Community support

</td> </tr> </table>

🏃‍♂️ Quick Start

🚀 Zero-install setup - Ready in 30 seconds!

Prerequisites

• Node.js 16 or higher
• An OpenRouter API key (get one at OpenRouter)

Zero-Config Installation

No build steps, no dependencies, no setup required:

# Set your OpenRouter API key
export OPENROUTER_API_KEY=your-api-key-here

# Run the server instantly
npx nexus-mcp --stdio

That's it! The server is now running and ready for MCP client connections.

Testing the NPX Installation

# Test the CLI help
npx nexus-mcp --help

# Test the version
npx nexus-mcp --version

# Run with your API key
OPENROUTER_API_KEY=your-key npx nexus-mcp --stdio

Alternative: Local Development Installation

For local development or customization:

1. Clone the repository:

git clone https://github.com/adawalli/nexus.git
cd nexus

2. Install dependencies:

npm install

3. Build the server:

npm run build

4. Configure your OpenRouter API key:

# 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:

npm start

Integration with MCP Clients

🚀 Quick Setup with NPX (Recommended)

The easiest way to integrate with any MCP client is using NPX:

Claude Code

Add this server to your Claude Code MCP settings:

1. Open your MCP settings file (usually ~/.claude/mcp_settings.json)

2. Add the server configuration using NPX:

{
  "mcpServers": {
    "nexus": {
      "command": "npx",
      "args": ["nexus-mcp", "--stdio"],
      "env": {
        "OPENROUTER_API_KEY": "your-api-key-here"
      }
    }
  }
}

3. Restart Claude Code

That's it! No installation, no build steps, no path configuration required.

Cursor

Configure the server in Cursor's MCP settings:

1. Open Cursor settings and navigate to MCP servers

2. Add a new server with:

   • Name: nexus
   • Command: npx
   • Args: ["nexus-mcp", "--stdio"]
   • Environment Variables:
     • OPENROUTER_API_KEY: your-api-key-here

3. Restart Cursor

Other MCP Clients

For any MCP-compatible client, use these connection details:

• Transport: stdio
• Command: npx
• Args: ["nexus-mcp", "--stdio"]
• Environment Variables: OPENROUTER_API_KEY=your-api-key-here

Alternative: Local Installation

If you prefer using a local installation (after following the local development setup):

{
  "mcpServers": {
    "nexus": {
      "command": "node",
      "args": ["/path/to/nexus-mcp/dist/cli.js", "--stdio"],
      "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: perplexity/sonar
- Max tokens: 2000
- Temperature: 0.3

Available Tools

search

The main search tool that provides AI-powered web search capabilities.

Parameters:

• query (required): Search query (1-2000 characters)
• model (optional): Perplexity model to use (default: "perplexity/sonar")
• maxTokens (optional): Maximum response tokens (1-4000, default: 1000)
• temperature (optional): Response randomness (0-2, default: 0.7)

Example Response:

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
- Sources: 5 found

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

NPX-Specific Issues

"npx: command not found"

• Ensure Node.js 16+ 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

NPX takes a long time to start

• This is normal on first run as NPX downloads the package
• 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
• 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 the --stdio flag is included in your MCP configuration
• Check that Node.js 16+ 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:

# Development with hot reload
npm run dev

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Lint code
npm run lint

# Format code
npm run format

💰 API Credits and Costs

This server uses OpenRouter's API, which charges based on token usage:

• Perplexity Sonar models: Check current pricing at OpenRouter Models
• Usage monitoring: Track consumption through the OpenRouter dashboard
• Cost control: Set usage limits in your OpenRouter account
• Optimization: Nexus includes built-in rate limiting and intelligent caching

📚 Documentation

<div align="center">

📖 Guide	🔗 Link	📝 Description
Quick Start	Getting Started	Zero-install setup in 30 seconds
API Reference	MCP Tools	Complete command reference
Configuration	Environment Setup	Advanced configuration options
Contributing	Contributing Guide	Join our open source community
Troubleshooting	Common Issues	Solutions to common problems

</div>

🤝 Contributing

We welcome contributions from developers of all experience levels!

<table> <tr> <td width="33%">

🚀 Get Started

• Fork the repository
• Read our Contributing Guide
• Check out good first issues

</td> <td width="33%">

🐛 Report Issues

• Bug Reports
• Feature Requests
• Ask Questions

</td> <td width="33%">

💬 Join Community

• GitHub Discussions
• Code of Conduct
• Roadmap & Project Board

</td> </tr> </table>

🌟 Recognition

Contributors are recognized in our:

• Contributors list
• Release notes for significant contributions
• Community spotlights and testimonials

🔗 Related Projects

• 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

📞 Support & Community

<div align="center">

💬 Need Help?	🔗 Resource
Quick Questions	GitHub Discussions
Bug Reports	GitHub Issues
Documentation	OpenRouter Docs • MCP Specification
Feature Requests	Enhancement Proposals

</div>

📄 License

MIT License - see LICENSE file for details.

---

<div align="center">

Made with ❤️ by the open source community

⭐ Star us on GitHub • 📦 View on NPM • 📚 Read the Docs

Nexus: AI integration without the complexity

</div>