Performs web searches using DuckDuckGo's search API, with support for general web searches and documentation-focused searches that prioritize technical domains.
Intelligently reads and extracts content from GitHub pages with automatic code-focused parsing that retains headers, code blocks, and tables while stripping conversational text.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Nexus MCP Serversearch for the latest Python 3.12 release notes and extract just the code changes"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
🌐 Nexus MCP Server
The Hybrid Search & Retrieval Engine for AI Agents.
Nexus is a local Model Context Protocol (MCP) server that combines the best features of Exa (semantic web search) and Ref (documentation-optimized reading). It provides your AI agent (Claude, Cursor, etc.) with the ability to search the web and extract surgical, token-efficient context from documentation without requiring external API keys.
✨ Features
1. Hybrid Search (nexus_search)
Nexus understands that searching for news is different from searching for API docs.
General Mode: Performs broad web searches (like Exa) to find articles, news, and general information.
Docs Mode: Automatically filters results to prioritize technical domains (
readthedocs,github,stackoverflow, official documentation).
2. Intelligent Reading (nexus_read)
Nexus doesn't just dump HTML into your context window. It parses content based on intent.
General Focus: Cleans articles, removing ads, navigation bars, and fluff. Perfect for reading news or blog posts.
Code Focus: Aggressively strips conversational text, retaining only Headers, Code Blocks, and Tables. This mimics
ref.tools, ensuring your model gets pure syntax without the noise.Auto-Detect: Automatically switches to "Code Focus" when visiting technical sites like GitHub or API references.
3. Privacy & Cost
No API Keys Required: Uses DuckDuckGo for search and standard HTTP requests for retrieval.
Runs Locally: Your data stays on your machine until the cleaned context is sent to the LLM.
🛠️ Installation
Prerequisites
Python 3.10+
Quick Install
Option 1: Using pip (Simplest - Works Everywhere)
Option 2: Using uvx (Faster, Isolated)
First install uv if you don't have it:
Then use uvx (no separate installation needed):
Development Install
For local development or contributing:
Clone the repository:
Install in development mode:
For development with testing tools:
⚙️ Configuration
Claude Code (CLI)
Option 1: Using pip (Simplest)
Option 2: Using uvx (Requires uv installation)
Make sure you have uv installed first (see Installation section above), then:
Option 3: Local Development Setup
If you cloned the repository for development:
Configuration Scopes:
--scope user- Available across all projects (recommended for GitHub install)--scope project- Creates.mcp.json(shareable via git)--scope local- Personal config in~/.claude.json
Check server status:
Claude Desktop / Cursor
Config Location:
MacOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.json
Option 1: Using pip (Simplest)
First install: pip install git+https://github.com/rcdelacruz/nexus-mcp.git
Then add to config:
Option 2: Using uvx (Requires uv installed)
Make sure uv is installed first (see Installation section), then add to config:
For local development:
If you cloned the repo and installed with pip install -e .:
Replace
🚀 Usage
Once connected, simply prompt Claude naturally. Nexus handles the tool selection.
Verify It's Working
Check server connection:
See VERIFICATION.md for detailed testing instructions.
Scenario 1: Technical Research (Ref Emulation)
User: "How do I use
asyncio.gatherin Python? Check the docs."
Nexus Action:
Search:
nexus_search(query="python asyncio gather", mode="docs")Read:
nexus_read(url="docs.python.org/...", focus="code")
Result: The AI receives only the function signature and code examples, saving context window space.
Scenario 2: General Research (Exa Emulation)
User: "Search for the latest updates on the NVIDIA Blackwell chip."
Nexus Action:
Search:
nexus_search(query="NVIDIA Blackwell updates", mode="general")Read:
nexus_read(url="techcrunch.com/...", focus="general")
Result: The AI reads a clean, ad-free summary of the news article.
🧠 Architecture
Nexus is built on the Model Context Protocol using the FastMCP Python SDK.
Component | Technology | Purpose |
MCP Framework |
| Server implementation and tool registration |
Search Backend |
| Free web search without API keys |
HTTP Client |
| Async HTTP requests with timeout handling |
HTML Parsing |
| Intelligent content extraction |
Doc Detection | Heuristic URL matching | Auto-detection of technical sites |
Production Features
✅ Comprehensive Error Handling - All edge cases covered with graceful fallbacks
✅ Input Validation - URL format, parameter bounds, and mode validation
✅ Proper Logging - Structured logging instead of print statements
✅ Configurable Limits - Timeouts, content length, and result counts
✅ 85% Test Coverage - 19 comprehensive unit tests
✅ Type Hints - Full type annotations for better IDE support
✅ Dependency Management - Modern pyproject.toml configuration
🧪 Testing
Run the test suite:
📊 Project Structure
🤝 Contributing
Contributions are welcome! Please ensure:
All tests pass (
pytest)Code coverage remains above 80%
Follow existing code style and patterns
Add tests for new features
📄 License
MIT License - See LICENSE file for details. Free to use and modify.