nexus-mcp-server

fabriziosalmi/nexus-mcp-server

3.2

If you are the rightful owner of nexus-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

Nexus MCP Server is a modular and configurable server designed to integrate a wide range of custom tools, making them accessible to a Large Language Model (LLM).

Tools
10
Resources
0
Prompts
0

🚀 Nexus MCP Server

Nexus is an advanced, modular, and configurable MCP (Model Context Protocol) server that acts as a central hub for integrating a wide range of custom tools, making them available to Large Language Models (LLMs) like Claude and VS Code Copilot.

📖 Quick Navigation

🎯 Key Features

🛠️ 120+ Tools across 17 categories

  • Mathematical Operations: Advanced calculator, statistics, financial calculations
  • Security & Cryptography: Password generation, encryption, vulnerability scanning
  • Code Generation: Project scaffolding, API generation, design patterns
  • File Operations: Format conversion, archiving, PDF processing
  • System Management: Process monitoring, Docker integration, Git operations
  • Network Tools: Security scanning, DNS lookups, website analysis
  • Data Processing: JSON/YAML manipulation, text analysis, validation

⚡ Advanced Capabilities

  • Dynamic Tool Creation: Create custom tools on-the-fly using create_and_run_tool
  • Web Configuration Interface: Real-time tool management without restarts
  • Docker Integration: Secure, isolated execution environments
  • Hot Reload: Update configurations without server downtime
  • Multi-Client Support: Works with VS Code, Claude Desktop, and HTTP API
  • Automatic Client Detection: VSCode gets curated 99-function subset, Claude Desktop gets full 437+ functions

🔒 Security First

  • Sandboxed file operations in safe_files/ directory
  • Input validation and sanitization
  • Resource limits and timeout protection
  • Path traversal prevention

📸 Screenshots

Claude Desktop Integration

Claude Desktop Integration

Tool Usage Examples

UUID Generation Example 1

UUID Generation Example 2

⚡ Quick Start

📋 Prerequisites

  • Python 3.8+
  • VS Code (for VS Code integration) or Claude Desktop (for Claude integration)
  • Docker (optional, for containerized deployment)

🚀 Installation

  1. Clone the repository

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

  2. Install dependencies

    pip install -r requirements.txt

  3. Start the MCP server

    python multi_server.py

  4. Test the installation

    python client.py add '{"a": 42, "b": 8}'
# Expected output: {"result": 50.0}

🔧 VS Code Setup

⚠️ Important: VS Code has a limit of 128 MCP tools. Nexus automatically uses a curated subset of tools (99 functions across 12 essential tools) for VS Code while providing the full tool suite for Claude Desktop.

Step 1: Install MCP Extension

  1. Open VS Code
  2. Go to Extensions (Ctrl/Cmd + Shift + X)
  3. Search for "Model Context Protocol" or "MCP"
  4. Install the official MCP extension

Step 2: Configure Settings

Option A: Using the VSCode-optimized configuration (Recommended)

Add to your VS Code settings.json:

{
  "mcp.servers": {
    "nexus-vscode": {
      "command": "./start_mcp_server_vscode.sh",
      "args": [],
      "cwd": "/absolute/path/to/nexus-mcp-server",
      "env": {
        "PYTHONPATH": "/absolute/path/to/nexus-mcp-server",
        "MCP_SERVER_NAME": "NexusServer-VSCode",
        "MCP_CLIENT_TYPE": "vscode",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

Option B: Manual configuration selection

{
  "mcp.servers": {
    "nexus": {
      "command": "python",
      "args": ["multi_server.py", "--config", "config-vscode.json"],
      "cwd": "/absolute/path/to/nexus-mcp-server",
      "env": {
        "PYTHONPATH": "/absolute/path/to/nexus-mcp-server",
        "MCP_SERVER_NAME": "NexusServer",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

VSCode Tool Limitations & Configuration

VS Code is limited to 128 MCP tools maximum. Nexus automatically detects VS Code and loads a curated configuration:

VSCode Configuration (99 functions across 12 tools):

  • calculator - Mathematical operations (16 functions)
  • string_tools - Text manipulation (11 functions)
  • crypto_tools - Encryption/security (11 functions)
  • encoding_tools - Text encoding/decoding (19 functions)
  • datetime_tools - Date/time operations (12 functions)
  • validator_tools - Data validation (5 functions)
  • uuid_tools - UUID generation (6 functions)
  • url_tools - URL operations (4 functions)
  • filesystem_reader - File operations (7 functions)
  • unit_converter - Unit conversions (6 functions)
  • web_fetcher - Web content fetching (1 function)
  • workflows - Workflow automation (1 function)

Claude Desktop Configuration:

  • All 46 tools available (437+ functions)

Step 3: Connect and Use

  1. Open Command Palette (Ctrl/Cmd + Shift + P)
  2. Run "MCP: Connect to Server"
  3. Select "nexus-vscode" from the list
  4. Use tools in Copilot Chat: @mcp generate_uuid4 {}

Troubleshooting VS Code

  • Server not starting: Ensure Python path is correct and dependencies are installed
  • Tools not available: Check VS Code Output panel → "Model Context Protocol" for errors
  • Permission errors: Verify the nexus-mcp-server directory has proper read permissions
  • Tool limit exceeded: Use the VSCode-specific configuration which limits tools to 99 functions

🤖 Claude Desktop Setup

Step 1: Locate Configuration File

Find your Claude Desktop configuration directory:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/claude/claude_desktop_config.json

Step 2: Add Server Configuration

Create or update the configuration file:

{
  "mcpServers": {
    "nexus": {
      "command": "python",
      "args": ["multi_server.py"],
      "cwd": "/absolute/path/to/nexus-mcp-server",
      "env": {
        "PYTHONPATH": "/absolute/path/to/nexus-mcp-server",
        "MCP_SERVER_NAME": "NexusServer",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

Step 3: Restart Claude Desktop

  1. Quit Claude Desktop completely
  2. Restart Claude Desktop
  3. Verify connection by asking Claude to use a tool: "Generate a UUID for me"

Alternative: Minimal Configuration

For testing with fewer tools, use the minimal configuration:

cp claude_desktop_config_minimal.json ~/Library/Application\ Support/Claude/claude_desktop_config.json

This provides 8 essential tools: Calculator, Crypto, DateTime, Encoding, String, System Info, UUID, and Validator tools.

Troubleshooting Claude Desktop

  • Server not connecting: Check the absolute paths in the configuration
  • Module not found errors: Ensure virtual environment is activated and dependencies installed
  • Permission denied: Make sure the directory and files are readable
  • Check logs: Look for [nexus] entries in Claude Desktop's application logs

🖥️ Web Configuration Interface

Nexus MCP Server includes a modern web interface for dynamic configuration management without needing to restart the server.

✨ Features

  • 🔧 Tools Dashboard: View and enable/disable tools with checkboxes
  • 📊 Real-time Metrics: Monitor enabled tools, active sessions, and performance
  • 📋 Log Streaming: Real-time server log display via Server-Sent Events
  • ⚡ Hot Reload: Apply changes without server downtime
  • 🎨 Responsive Design: Works on desktop and mobile

🚀 Starting the Web Interface

# Start the UI server on port 8888
python ui_server.py

# Access the web dashboard
open http://localhost:8888

🔧 Using the Interface

  1. View Available Tools: See all tools in the left panel
  2. Enable/Disable Tools: Use checkboxes to select tools
  3. Apply Changes: Click "Apply Changes" to update configuration
  4. Monitor Metrics: Watch real-time metrics in the right panel
  5. View Logs: Monitor server activity in the bottom panel

🐳 Docker Support

Nexus MCP Server includes comprehensive Docker support for easy deployment and isolation:

Quick Start with Docker

# Build and run with Docker Compose
docker-compose up nexus-mcp

# Or build manually
docker build -t nexus-mcp-server .
docker run --rm -i nexus-mcp-server

Custom Configuration

# Run with custom volume mapping
docker run --rm -i \
  -v "./safe_files:/app/safe_files:rw" \
  -v "./config.json:/app/config.json:ro" \
  nexus-mcp-server:latest

Environment Variables

# Configure the container
export PYTHONUNBUFFERED=1
export MCP_SERVER_NAME=NexusServer
export LOG_LEVEL=INFO

📋 Tools Overview

🛠️ Available Tools: 120+ ⚙️ Total Functions: 500+

🗂️ Tool Categories

CategoryToolsDescription
MathematicalCalculator, Statistics, Unit ConverterAdvanced calculations, statistical analysis, unit conversions
SecurityCrypto Tools, Security Scanner, Password GeneratorEncryption, vulnerability scanning, secure token generation
DevelopmentCode Generator, Git Tools, Docker ManagerProject scaffolding, version control, container management
File OperationsFile Converter, Archive Tools, PDF ProcessorFormat conversion, compression, document processing
SystemSystem Info, Process Manager, Performance MonitorSystem monitoring, resource management, performance analysis
NetworkNetwork Tools, Security Scanner, DNS LookupNetwork diagnostics, security assessment, connectivity tools
Data ProcessingJSON/YAML Tools, Text Analysis, Data ValidatorData manipulation, text processing, validation
String OperationsString Tools, Regex Engine, Encoding/DecodingText manipulation, pattern matching, encoding conversion

📋 For complete tool documentation with examples and parameters, see

🚀 Key Features

Dynamic Tool Creation

Create custom tools on-the-fly with create_and_run_tool:

# Example: Custom date converter
code = '''
from datetime import datetime
custom_date = "20250907-143022"
date_part, time_part = custom_date.split('-')
dt = datetime(int(date_part[:4]), int(date_part[4:6]), int(date_part[6:8]),
              int(time_part[:2]), int(time_part[2:4]), int(time_part[4:6]))
print(f"ISO format: {dt.isoformat()}")
'''
result = create_and_run_tool(code, timeout=30, memory_limit_mb=64)
HTTP API Access

Access tools via REST API from any programming language:

# Example API calls
curl -X POST http://localhost:9999/tools/add/execute \
  -H "Content-Type: application/json" \
  -d '{"arguments": {"a": 15, "b": 27}}'

curl http://localhost:9999/tools/generate_uuid4/execute
Monitoring & Observability
  • Prometheus Metrics: Built-in metrics for monitoring tool usage
  • Real-time Logs: Live log streaming via web interface
  • Performance Tracking: Execution time and error rate monitoring

📚 Documentation

📋 Main Documentation

  • - Complete tools reference with 500+ functions, usage examples, and technical details

🔧 Advanced Features Documentation

  • - Runtime tool creation with create_and_run_tool
  • - REST API access for any programming language
  • - Advanced web dashboard configuration and API endpoints

🚀 Deployment & Operations

  • - Production deployment guides, Docker configurations, and best practices
  • - Production monitoring, metrics, and observability setup

🎯 Core Design Principles

  • 🎭 Modular Architecture: Distributed tool logic with central orchestration
  • ⚙️ Configuration-Driven: Enable/disable tools via config.json without recompilation
  • 🔒 Security First: Rigorous security controls in every tool
  • 📚 Self-Documenting: Comprehensive documentation and examples
  • 🔄 Workflow Support: Meta-tools for complex operation chains
  • 🚀 Runtime Flexibility: Dynamic tool creation and hot configuration reload

🔒 Security Features

  • Sandboxed Operations: File operations restricted to safe_files/ directory
  • Input Validation: Comprehensive sanitization of all parameters
  • Resource Limits: Memory, CPU, and timeout protection
  • Path Traversal Prevention: Secure file access controls
  • Docker Isolation: Optional containerized execution for enhanced security

🤝 Contributing

Contributions are welcome! Please see our contributing guidelines and feel free to submit issues and pull requests.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Nexus MCP Server - Empowering LLMs with advanced tool orchestration and secure execution environments.