# Nexus Mcp Server

> Yet another MCP server with custom tools support.

- **Type:** MCP server
- **Install:** `agentstack add mcp-fabriziosalmi-nexus-mcp-server`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [fabriziosalmi](https://agentstack.voostack.com/s/fabriziosalmi)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [fabriziosalmi](https://github.com/fabriziosalmi)
- **Source:** https://github.com/fabriziosalmi/nexus-mcp-server
- **Website:** https://fabriziosalmi.github.io/nexus-mcp-server/

## Install

```sh
agentstack add mcp-fabriziosalmi-nexus-mcp-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 🚀 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](#-key-features)
- [📸 Screenshots](#-screenshots)
- [⚡ Quick Start](#-quick-start)
- [🔧 VS Code Setup](#-vs-code-setup)
- [🤖 Claude Desktop Setup](#-claude-desktop-setup)
- [🖥️ Web Interface](#️-web-configuration-interface)
- [🐳 Docker Support](#-docker-support)
- [📋 Tools Overview](#-tools-overview)
- [📚 Documentation](#-documentation)

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

### Tool Usage Examples

## ⚡ 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**
   ```bash
   git clone https://github.com/fabriziosalmi/nexus-mcp-server.git
   cd nexus-mcp-server
   ```

2. **Install dependencies**
   ```bash
   pip install -r requirements.txt
   ```

3. **Start the MCP server**
   ```bash
   python multi_server.py
   ```

4. **Test the installation**
   ```bash
   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`:

```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**

```json
{
  "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:

```json
{
  "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:

```bash
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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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

| Category | Tools | Description |
|----------|--------|-------------|
| **Mathematical** | Calculator, Statistics, Unit Converter | Advanced calculations, statistical analysis, unit conversions |
| **Security** | Crypto Tools, Security Scanner, Password Generator | Encryption, vulnerability scanning, secure token generation |
| **Development** | Code Generator, Git Tools, Docker Manager | Project scaffolding, version control, container management |
| **File Operations** | File Converter, Archive Tools, PDF Processor | Format conversion, compression, document processing |
| **System** | System Info, Process Manager, Performance Monitor | System monitoring, resource management, performance analysis |
| **Network** | Network Tools, Security Scanner, DNS Lookup | Network diagnostics, security assessment, connectivity tools |
| **Data Processing** | JSON/YAML Tools, Text Analysis, Data Validator | Data manipulation, text processing, validation |
| **String Operations** | String Tools, Regex Engine, Encoding/Decoding | Text manipulation, pattern matching, encoding conversion |

> 📋 **For complete tool documentation with examples and parameters, see [TOOLS.md](TOOLS.md)**

### 🚀 Key Features

#### Dynamic Tool Creation
Create custom tools on-the-fly with `create_and_run_tool`:
```python
# 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:
```bash
# 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
- **[TOOLS.md](TOOLS.md)** - Complete tools reference with 500+ functions, usage examples, and technical details

### 🔧 Advanced Features Documentation
- **[Dynamic Tools](DYNAMIC_TOOLS.md)** - Runtime tool creation with `create_and_run_tool`
- **[Enhanced API](ENHANCED_API.md)** - REST API access for any programming language
- **[Web Interface](UI_CONFIGURATION.md)** - Advanced web dashboard configuration and API endpoints

### 🚀 Deployment & Operations
- **[Docker Deployment](DEPLOYMENT.md)** - Production deployment guides, Docker configurations, and best practices
- **[Prometheus Monitoring](PROMETHEUS_MONITORING.md)** - 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.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [fabriziosalmi](https://github.com/fabriziosalmi)
- **Source:** [fabriziosalmi/nexus-mcp-server](https://github.com/fabriziosalmi/nexus-mcp-server)
- **License:** MIT
- **Homepage:** https://fabriziosalmi.github.io/nexus-mcp-server/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-fabriziosalmi-nexus-mcp-server
- Seller: https://agentstack.voostack.com/s/fabriziosalmi
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.