⚡ superskills-mcp

⚡ superskills-mcp

superskills-mcp is a lightweight, globally installable Model Context Protocol (MCP) gateway. It allows you to effortlessly expose your local bash scripts, python tools, or Node.js skills to any AI assistant (ChatGPT, Claude Desktop, Cursor, etc.) via a unified interface.

Instead of writing a custom MCP server for every small script you create, superskills-mcp acts as a dynamic registry. You simply drop your skill's path into the configuration, and it is instantly available to the AI.

✨ Key Features

• 🌍 Global Installation: Run it from anywhere on your system via the superskills-mcp CLI.
• 🔌 Dynamic Tool Registration: Add or remove skills dynamically without touching the server code.
• 🔄 Hot Reloading: Apply configuration changes on the fly with zero downtime using superskills-mcp reload.
• 📝 Native Logging: Built-in background daemon management and real-time log tailing.
• 🛡️ Secure Execution: Strict path validations, restricted runner boundaries, and input schema validation via Zod.
• 🌐 Multi-Transport Support: Expose tools over HTTP (for ChatGPT/Ngrok) or Stdio (for local Claude/Cursor).

🚀 Quick Start

1. Installation

Install the CLI tool globally via npm or pnpm:

npm install -g superskills-mcp

2. Initialization

Generate your global configuration file (this will safely create ~/.superskills/mcp-config.json):

superskills-mcp init

3. Start the Gateway

Launch the MCP server in the background:

superskills-mcp serve &

(You can verify it is running by typing superskills-mcp status or by checking curl http://127.0.0.1:8787/health)

🛠️ CLI Reference

superskills-mcp comes with a powerful suite of management commands akin to PM2 or Nginx:

📦 Managing Skills

Adding Skills Automatically

You can use the CLI to dynamically attach a new local skill:

superskills-mcp add /path/to/your/custom_skill

Note: This command extracts the skill name and description, but sets the input schema to {}. If your skill requires specific arguments (like url or query), open ~/.superskills/mcp-config.json and define the JSON schema under the input key.

Removing Skills

To detach a skill:

superskills-mcp remove my_custom_skill

Applying Changes

After adding, removing, or manually editing your config, reload the gateway:

superskills-mcp reload

⚙️ Configuration File Structure

Your global configuration lives at ~/.superskills/mcp-config.json.

{
  "server": {
    "name": "superskills-mcp",
    "version": "0.4.0",
    "transport": "http",
    "host": "127.0.0.1",
    "port": 8787
  },
  "defaults": {
    "timeoutMs": 120000,
    "maxOutputBytes": 10485760,
    "runner": {
      "command": "bun",
      "args": ["{serverDir}/scripts/mcp-adapter.ts"]
    }
  },
  "skills": [
    {
      "name": "read_x_to_markdown",
      "description": "Read a given X/Twitter link and return clean Markdown.",
      "skillDir": "/Users/username/my-skills/twitter-scraper",
      "input": {
        "url": {
          "type": "string",
          "format": "uri",
          "description": "X/Twitter post URL to read"
        }
      },
      "env": {
        "KEEP_OUTPUT": "false"
      }
    }
  ]
}

• defaults.runner.args: The {serverDir} placeholder is automatically replaced with this gateway's actual installation path.
• skills[].input: Defines the exact JSON schema that the AI must fulfill when calling your tool.
• skills[].env: Environment variables scoped specifically to that single skill's execution.

🔗 Connecting AI Assistants

🌐 Connecting to ChatGPT (HTTP Transport)

For cloud-based AI like ChatGPT, the server must be exposed to the internet.

1. Ensure the gateway is running (superskills-mcp serve &).
2. Expose the local port via a persistent Ngrok tunnel:

ngrok http --domain=your-free-static-domain.ngrok-free.app 8787

3. In your ChatGPT MCP Configuration, provide the proxy URL with the /mcp path:https://your-free-static-domain.ngrok-free.app/mcp

Tip: You can test if the proxy is bypassing Ngrok's browser warnings by running:curl -H "ngrok-skip-browser-warning: true" https://your-free-static-domain.ngrok-free.app/health

🖥️ Connecting to Claude Desktop / Cursor (Stdio Transport)

Local clients prefer communicating via standard input/output (stdio). You do not need to run serve & manually for these clients; they will spawn the gateway themselves.

Add this block to your local client config (e.g., ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "superskills-mcp": {
      "command": "superskills-mcp",
      "args": ["serve", "--transport", "stdio"]
    }
  }
}

🔒 Security Principles

• Isolated Execution: Skills are executed using restricted runners without shell interpolation (shell: false), eliminating command injection risks.
• Directory Verification: The gateway strictly validates that runner scripts exist within the trusted serverDir or the specific skillDir.
• Resource Limits: Configurable timeoutMs and maxOutputBytes prevent runaway scripts from crashing your system.