Nexus

Nexus MCP Server is a local context-server that lets your AI agents search the web and extract clean, token-efficient context from documentation without external API keys. It offers hybrid search and intelligent reading to tailor results for technical docs or general information, all running locally on your machine.

How to use

You connect Nexus to your MCP client and start sending requests through the MCP interface your client provides. Use Nexus to perform two core actions: search and read. For code-focused inquiries, Nexus delivers syntax-ready snippets and code blocks, while for general information it cleans articles to remove noise like ads and navigation bars. If you visit technical sites, Nexus auto-switches to a code-oriented reading mode to maximize usefulness in your prompt.

Typical workflows you’ll use are:

How to install

Prerequisites: Python 3.10 or newer.

Choose an installation method and follow the steps below.

Option 1: Using pip (simplest and widely compatible)

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

Option 2: Using uvx for faster isolated runs

# Install uv if you don’t have it
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or on Windows use the PowerShell installer
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Start using uvx with the nexus-mcp project
uvx --from git+https://github.com/rcdelacruz/nexus-mcp.git nexus-mcp

Option 3: Local development setup (for contributors)

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

# Create and activate a virtual environment
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install in editable mode
pip install -e .

# Optional: install development tools
pip install -e ".[dev]"

Configuration and runtime notes

You can connect Nexus to your MCP client in two ways: as a remote HTTP server or as a local stdio server started by your client. The source provides explicit commands for setting up Nexus within Claude Code workflows and for local development. Follow the stdio approach if you want a fully local setup that starts with a Python runtime.

If you are working with Claude Code, you can register Nexus as an MCP server so your editor or assistant can invoke it directly. The process in the guide is to add Nexus with stdio transport at the user scope, which makes it available across projects.

Examples and quick start

Local development start example shows how to run Nexus via Python in a virtual environment and connect it to Claude. You will replace the placeholders with your actual paths.

# Add to Claude (example CLI invocation shown in the setup steps)
claude mcp add nexus --transport stdio --scope user -- nexus-mcp

# Or, for a project-scoped setup using a local Python runtime
# (in the development flow, you would point Claude to the Python interpreter and nexus_server.py)

Troubleshooting and tips

If you don’t see Nexus listed as connected, verify your runtime paths and that the virtual environment is activated. Ensure the Python interpreter path and nexus_server.py path are correct in your local setup. Check that your MCP client is configured to use the stdio transport for the nexus server and that the server process has the necessary permissions to run.

Security, privacy, and data handling

Nexus runs locally and uses DuckDuckGo for search and standard HTTP requests for retrieval. Your data stays on your machine until you send the cleaned context to your LLM, ensuring privacy and minimizing data exposure.

Architecture overview

Nexus is built on the Model Context Protocol using a Python SDK. It combines a local search backend with intelligent reading to produce compact, high-signal context for your models.

Available tools

nexus_search

Performs both broad general web searches and targeted documentation searches. Supports mode selection (general vs docs) to tailor results for news or API docs.

nexus_read

Parses and cleans retrieved content based on intent, with modes for general reading and code-focused extraction that preserves headers, code blocks, and tables. Automatically switches to code focus on technical sites.