Skip to main content
Glama
rcdelacruz

Nexus MCP Server

by rcdelacruz
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

🌐 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+

  • uv (Recommended) or pip

Quick Install (Recommended)

Install directly from GitHub - no cloning needed:

# Using uvx (no installation, runs on-demand) uvx --from git+https://github.com/rcdelacruz/nexus-mcp.git nexus-mcp # Or install with pip pip install git+https://github.com/rcdelacruz/nexus-mcp.git

Development Install

For local development or contributing:

  1. Clone the repository:

git clone https://github.com/rcdelacruz/nexus-mcp.git cd nexus-mcp

  1. Install in development mode:

# Create virtual environment python3 -m venv .venv source .venv/bin/activate # On Windows: .venv\Scripts\activate # Install the package in editable mode pip install -e .

  1. For development with testing tools:

pip install -e ".[dev]"

⚙️ Configuration

Claude Code (CLI)

Quick Setup (Recommended - Install from GitHub):

# Add the server globally (available in all projects) claude mcp add nexus --scope user -- \ uvx --from git+https://github.com/rcdelacruz/nexus-mcp.git nexus-mcp # Verify installation claude mcp list # Should show: ✓ Connected

Alternative: Local Development Setup

If you cloned the repository for development:

# Navigate to nexus-mcp directory cd /path/to/nexus-mcp # Install dependencies first python3 -m venv .venv source .venv/bin/activate pip install -e . # Add the server to Claude Code (project scope) claude mcp add nexus --scope project -- \ $(pwd)/.venv/bin/python $(pwd)/nexus_server.py # Verify installation claude mcp list

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 mcp list # Should show: nexus - ✓ Connected /mcp # In conversation: shows available tools

Claude Desktop / Cursor

Config Location:

  • MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Recommended: Install from GitHub with uvx

{ "mcpServers": { "nexus": { "command": "uvx", "args": [ "--from", "git+https://github.com/rcdelacruz/nexus-mcp.git", "nexus-mcp" ] } } }

Alternative: Using local installation

After running pip install git+https://github.com/rcdelacruz/nexus-mcp.git:

{ "mcpServers": { "nexus": { "command": "nexus-mcp" } } }

For local development:

If you cloned the repo and installed with pip install -e .:

{ "mcpServers": { "nexus": { "command": "/ABSOLUTE/PATH/TO/.venv/bin/python", "args": ["/ABSOLUTE/PATH/TO/nexus_server.py"] } } }

Replace

🚀 Usage

Once connected, simply prompt Claude naturally. Nexus handles the tool selection.

Verify It's Working

Check server connection:

claude mcp list # Should show: nexus - ✓ Connected # In a Claude Code conversation: /mcp # Should show nexus with 2 tools available

See VERIFICATION.md for detailed testing instructions.

Scenario 1: Technical Research (Ref Emulation)

User: "How do I use asyncio.gather in Python? Check the docs."

  • Nexus Action:

    1. Search: nexus_search(query="python asyncio gather", mode="docs")

    2. 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:

    1. Search: nexus_search(query="NVIDIA Blackwell updates", mode="general")

    2. 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

FastMCP

Server implementation and tool registration

Search Backend

DDGS

(DuckDuckGo)

Free web search without API keys

HTTP Client

httpx

Async HTTP requests with timeout handling

HTML Parsing

BeautifulSoup4

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:

# Activate virtual environment source .venv/bin/activate # Run all tests with coverage pytest # Run specific test file pytest tests/test_nexus_server.py -v # Run manual integration test python test_manual.py

📊 Project Structure

nexus-mcp/ ├── nexus_server.py # Main MCP server implementation ├── tests/ # Comprehensive test suite │ ├── __init__.py │ └── test_nexus_server.py ├── test_manual.py # Manual integration testing ├── pyproject.toml # Project configuration & dependencies ├── LICENSE # MIT License ├── README.md # This file └── .gitignore # Git ignore rules

🤝 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.

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

Resources

New MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/rcdelacruz/nexus-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server