MCP Desktop Gateway

Universal MCP (Model Context Protocol) Gateway for Claude Desktop - a Python-based bridge with built-in tools for system automation.

Features

• 🔧 Built-in Connectors: Shell commands, AppleScript automation, and more
• 🌐 Extensible Architecture: Add custom connectors via HTTP API
• 🚀 Automatic Setup: One-command installation with automatic Claude Desktop configuration
• 🔐 Security Features: Command filtering, timeouts, and sandboxing
• 📦 Zero Config: Works out of the box with intelligent configuration detection

Quick Start

1. Install via NPM

npm install -g @bobmatnyc/mcp-desktop-gateway

This will:

• Install the MCP Gateway CLI
• Set up a Python virtual environment
• Install all Python dependencies automatically
• Automatically configure Claude Desktop with MCP Gateway

2. Restart Claude Desktop

That's it! The installation automatically configures Claude Desktop for you.

If you need to reconfigure manually, use:

mcp-desktop-gateway config

3. Start Using

The gateway is now available with these built-in tools:

Shell Tools

• execute_command - Run shell commands safely
• list_directory - Browse the filesystem
• get_system_info - Get system information

AppleScript Tools (macOS only)

• run_applescript - Execute AppleScript code
• system_notification - Show notifications
• control_app - Control applications
• get_clipboard/set_clipboard - Manage clipboard

Gateway Tools

• list_connectors - List active connectors
• gateway_health - Check gateway status
• hello_world - Test the connection

Usage Examples

In Claude Desktop, you can now:

// List files in current directory
execute_command(command="ls -la")

// Show a notification (macOS)
system_notification(title="Task Complete", message="Your build finished!")

// Get system information
get_system_info()

Advanced Usage

Custom Configuration

Create a config/config.yaml file:

server:
  name: "mcp-desktop-gateway"
  version: "1.0.0"
  log_level: "INFO"

connectors:
  - name: shell
    enabled: true
    config:
      timeout: 30
      working_directory: "/Users/me/projects"

Adding Custom Connectors

MCP Gateway supports external connectors via HTTP. See the documentation for details on creating custom connectors.

Troubleshooting

Python Not Found

MCP Gateway requires Python 3.8+. Install it from:

• macOS: brew install python3
• Ubuntu/Debian: sudo apt install python3 python3-pip python3-venv
• Windows: Download from python.org

Permission Errors

If you get permission errors during installation:

sudo npm install -g @bobmatnyc/mcp-desktop-gateway

Gateway Not Connecting

1. Check the logs: ~/Library/Logs/Claude/mcp-server-mcp-desktop-gateway.log
2. Verify Python path: mcp-desktop-gateway setup
3. Test manually: mcp-desktop-gateway

Development

# Clone the repository
git clone https://github.com/user/mcp-desktop-gateway
cd mcp-desktop-gateway

# Install in development mode
npm install
npm run setup

# Run tests
npm test

License

MIT - See LICENSE file for details

Contributing

Contributions are welcome! Please see our Contributing Guide for details.

Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions