MCP Guardrail Server

Read this in other languages: 日本語

MCP Guardrail Server is a secure MCP (Model Context Protocol) server that executes only pre-authorized commands. It can be used in high-security environments to provide AI assistants with limited command execution capabilities.

Features

• Executes only commands included in the allowlist
• Restricts file access to pre-authorized paths only
• Command execution timeout functionality

Installation

npm install
npm run build

Usage

npm start -- [--allowed-commands <comma-separated-list>] [--path-config <path-to-config-file>]

Options

• --allowed-commands: Comma-separated list of allowed Bash commands (optional, default: git,ls,mkdir,cd,npm,npx,python)
• --path-config: Path to a JSON configuration file specifying allowed file paths (optional)

Examples

# Run in development mode
npm run dev

# Start server (using default allowed commands)
npm start

# Start with custom command list
npm start -- --allowed-commands git,ls,node

# Start with path restrictions
npm start -- --path-config ./path-config.json

Path Configuration

To restrict file access to specific directories, create a configuration file based on the sample:

# Copy the sample configuration file
cp path-config.sample.json path-config.json

# Edit the configuration file to match your needs
nano path-config.json

The path configuration file should have this format:

{
  "allowedPaths": [
    "/tmp",
    "/Users/username/Documents/project",
    "/var/log",
    "C:\\Users\\username\\Documents\\project",
    "C:\\Windows\\Temp"
  ]
}

Include paths for both Windows and macOS as needed for your environment.

Configuration with Claude Desktop

To use this MCP server with Claude Desktop, add the following entry to your Claude Desktop configuration file (typically ~/.config/Claude Desktop/claude_desktop_config.json):

{
  "mcpServers": {
    "guardrail": {
      "command": "node",
      "args": [
        "/absolute/path/to/dist/index.js",
        "--allowed-commands",
        "git,ls,node,echo", // Add your allowed commands here
        "--path-config",
        "/absolute/path/to/path-config.json" // Add your path config file
      ],
      "env": {}
    }
  }
}

Connectivity Test

To verify that the server is working correctly, run:

npm test

This will run the following tests:

• Executing an allowed command
• Attempting to execute an unauthorized command (which should be rejected)
• Accessing a file in an allowed path (should be permitted)
• Attempting to access a file in a restricted path (which should be rejected)

Security Notes

• Only allow commands that are absolutely necessary
• Do not allow potentially dangerous commands (such as rm -rf)
• Restrict file access to only the paths that are needed
• Be especially careful with paths that contain sensitive data or system files

License

MIT