local-mcp-server

mpklu/local-mcp-server

3.2

If you are the rightful owner of local-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.

A universal Model Context Protocol (MCP) server that automatically discovers and exposes local scripts to AI assistants through a modern web interface.

Tools
5
Resources
0
Prompts
0

Local MCP Server

A universal Model Context Protocol (MCP) server that automatically discovers and exposes local tools to AI assistants through a modern web interface and pluggable host adapter system.

🌟 Features

  • MCP 1.25.0 Compliant: Latest protocol features including tool titles and annotations
  • Directory-Based Auto-Discovery: Automatically detects tools organized in individual folders under tools/
  • Universal Host Support: Works with Claude Desktop, Generic MCP clients, and Google Gemini CLI through pluggable adapters
  • Intelligent Discovery Pipeline: Auto-generates configurations for new tools with dual-config system
  • Visual Management: Modern React-based web interface for tool configuration and monitoring
  • Host Adapter Architecture: Pluggable system supporting different MCP communication protocols
  • Tool Annotations: Automatic classification of tools as read-only or destructive for better AI understanding
  • Dependency Isolation: Each tool gets its own virtual environment with automatic dependency management
  • Secure Execution: Comprehensive security with resource limits, sandboxing, and input validation
  • Real-time Monitoring: Live server status, execution monitoring, and configuration management

🔒 Security Features

Local MCP Server implements multiple layers of security to protect your system:

Input Validation & Sanitization

  • Path Traversal Protection: Multi-layer validation prevents access outside allowed directories
  • Configurable Workspaces: Each tool can define allowed paths with special variables ({TOOL_DIR}, {HOME}, {TEMP})
  • Parameter Validation: Type checking, required field enforcement, and format validation from @param annotations
  • Prompt Injection Detection: Scans input for malicious patterns attempting to manipulate AI behavior
  • String Sanitization: Null byte filtering, length limits, and control character removal

Sensitive Data Protection

  • Automatic Redaction: Detects and redacts 30+ sensitive keywords (passwords, API keys, tokens, secrets)
  • Pattern-Based Detection: Regex patterns catch credit cards, SSNs, AWS keys, GitHub tokens, GitLab PATs, JWTs, private keys
  • Dual Redaction Styles:
    • Full redaction (***REDACTED***) for regular logs
    • Hint-style (<redacted:14_chars:key:password>) for audit logs with debugging context
  • Configurable Scope: Control which data gets redacted (arguments, outputs, or both)

Resource Limits (Unix/Linux/macOS)

  • CPU Time Limits: Prevent runaway processes (default: 60 seconds per execution)
  • Memory Limits: Cap virtual memory usage (default: 512MB per tool)
  • Process Limits: Restrict child process creation (default: 10 processes)
  • File Size Limits: Prevent disk space exhaustion (default: 100MB per file)
  • Graceful Degradation: Automatically disabled on Windows, other protections remain active

Execution Controls

  • Concurrent Execution Limits: Maximum simultaneous tool executions (default: 5)
  • Rate Limiting: Per-tool execution limits using sliding window algorithm (default: 10/minute)
  • Confirmation Requirements: Optional manual approval before destructive operations
  • Tool Whitelisting: Only explicitly configured tools can execute
  • Process Isolation: Each tool runs in separate subprocess with captured I/O

Temporary File Management

  • Automatic Cleanup: Removes old temporary files on server startup based on retention policy
  • Configurable Retention: Set how long to keep temp files (default: 24 hours)
  • Statistics Tracking: Logs cleanup results showing directories removed and space freed
  • Disk Space Protection: Prevents accumulation of stale temp files from tool executions
  • On-Demand Control: Enable/disable cleanup via auto_cleanup_temp config flag

Audit Logging

  • Structured JSON Logs: Machine-parsable logs with ISO8601 timestamps
  • Request Correlation: UUID-based request IDs thread through entire execution chain
  • Separate Audit Trail: Dedicated audit.log for security events and tool lifecycle
  • Rotating File Handlers: Automatic log rotation (10MB max, 5 backups)
  • Execution Tracking: Start/end events, execution time, success/failure, exit codes

Configuration

All security features are configurable via config/global.json:

{
  "enable_resource_limits": true,
  "max_cpu_seconds": 60,
  "max_memory_mb": 512,
  "max_processes": 10,
  "max_file_size_mb": 100,
  "max_concurrent_executions": 5,
  "enable_rate_limiting": true,
  "max_executions_per_minute": 10,
  "redact_sensitive_data": true,
  "enable_audit_logging": true,
  "auto_cleanup_temp": true,
  "temp_retention_hours": 24
}

See for complete security settings.

🎯 MCP 1.25.0 Features

Local MCP Server supports the latest Model Context Protocol features:

Tool Titles

Tools now have human-friendly display names that appear in AI assistant interfaces:

  • file-ops → "File Operations"
  • http-client → "HTTP Client"
  • system-info → "System Information"

Titles are automatically generated from tool names or can be customized in tool configs.

Tool Annotations

Tools are automatically classified with semantic flags for better AI understanding:

  • Read-Only 🔍: Tool only reads data, doesn't modify system (e.g., system-info, http-client)
  • Destructive 💥: Tool performs operations that modify files or data (e.g., file-ops with write capabilities)

These annotations help AI assistants make better decisions about when to use each tool and what precautions to take.

🚀 Quick Start

Prerequisites

Installation

  1. Clone the repository

    git clone https://github.com/yourusername/local-mcp-server.git
cd local-mcp-server

  2. Start the development environment

    # This will set up both server and web interface
./scripts/setup.sh

  3. Add your first tool

    • Create a folder in tools/ with your tool name (e.g., tools/my-tool/)
    • Copy the template: cp tools/TEMPLATE/run.sh tools/my-tool/run.sh
    • Add your tool logic (Python, Node.js, or any executable)
    • Edit run.sh to call your tool
    • Run python server/discover_tools.py to auto-generate configuration
    • Open http://localhost:3000 to configure it via the web interface
    • The tool will automatically appear in your MCP-compatible AI assistant

Configure with Your MCP Host

Claude Desktop (Default)
{
  "mcpServers": {
    "local-tools": {
      "command": "/path/to/local-mcp-server/server/start_server.sh",
      "args": ["--host=claude-desktop"],
      "cwd": "/path/to/local-mcp-server/server"
    }
  }
}
Generic MCP Client
# Start server for any MCP-compatible client
./server/start_server.sh --host=generic
Google Gemini CLI
# Start server for Google Gemini CLI
./server/start_server.sh --host=google-gemini-cli

See for detailed configuration instructions and supported features.

⚙️ Advanced Configuration

Custom Tools Directory

By default, tools are discovered in the tools/ directory, but you can specify a custom location:

# Discovery with custom tools directory
python server/discover_tools.py --tools-dir=/path/to/my/tools

# Start server with custom tools directory
./server/start_server.sh --tools-dir=/path/to/my/tools

# Or in Claude Desktop config
{
  "mcpServers": {
    "local-tools": {
      "command": "/path/to/local-mcp-server/server/start_server.sh",
      "args": ["--tools-dir", "/custom/tools", "--host=claude-desktop"],
      "cwd": "/path/to/local-mcp-server/server"
    }
  }
}

This is useful for:

  • Separating tools across different projects
  • Using shared tool repositories
  • Docker volume mounts
  • Multi-tenant deployments

📁 Project Structure

local-mcp-server/
├── server/                    # MCP server core
│   ├── src/local_mcp/        # Main server code
│   │   ├── adapters/         # Host adapter system
│   │   ├── config.py         # Configuration management
│   │   ├── discovery.py      # Tool discovery system
│   │   └── server.py         # Main MCP server
│   ├── config/               # Server configurations
│   │   ├── tools/            # Individual tool configs
│   │   ├── tools.json        # Compiled tool config
│   │   └── config_templates/ # Host-specific templates
│   ├── discover_tools.py     # Discovery tool utility
│   ├── build_tools.py        # Config compilation utility
│   └── start_server.sh       # Server startup script
├── web-interface/            # Web management interface
│   ├── backend/              # FastAPI backend
│   ├── frontend/             # React frontend
│   └── start_dev.sh          # Development server
├── tools/                    # Directory-based tools (each in own folder)
│   ├── demo-features/        # Sample: Advanced features showcase
│   ├── file-ops/             # Sample: File operations
│   ├── http-client/          # Sample: HTTP utilities
│   ├── system-info/          # Sample: System information
│   └── text-utils/           # Sample: Text processing
├── docs/                     # Documentation
└── examples/                 # Host-specific configuration examples

🛠️ Sample Tools

The project includes several sample tools to help you get started:

  • System Info: Get system information and metrics
  • File Operations: File reading, writing, and listing utilities
  • Text Processing: Text manipulation and analysis tools
  • HTTP Client: Make HTTP requests and API calls
  • Demo Features: Showcase advanced configuration features

📚 Documentation

🤝 Contributing

We welcome contributions! Please see our for details.

📄 License

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

🆘 Support