ShellCheck MCP Server

A Model Context Protocol (MCP) server that provides shell script linting via ShellCheck. Allows AI agents to analyze shell scripts for common errors, stylistic issues, and potential bugs.

MCP Server Profile

{
  "name": "mcp-shellcheck",
  "description": "A Model Context Protocol (MCP) server that provides shell script linting via ShellCheck for AI coding assistants",
  "tools": [
    {
      "name": "shellcheck",
      "description": "Run ShellCheck on a shell script to find bugs, stylistic issues, and potential errors",
      "inputSchema": {
        "type": "object",
        "properties": {
          "file_path": { "type": "string", "description": "Path to the shell script file to check" },
          "script_content": { "type": "string", "description": "Raw shell script content to check" },
          "shell": { "type": "string", "description": "Shell type to check", "enum": ["bash", "sh", "dash", "ksh", "ash"] },
          "check_sourced": { "type": "boolean", "description": "Enable checks for sourced files" },
          "enable_all": { "type": "boolean", "description": "Enable all optional checks" },
          "exclude": { "type": "string", "description": "Comma-separated list of warning codes to exclude" },
          "severity": { "type": "string", "description": "Minimum severity to report", "enum": ["error", "warning", "info", "style"] }
        }
      }
    },
    {
      "name": "shellcheck_info",
      "description": "Get information about the ShellCheck version and server capabilities",
      "inputSchema": {
        "type": "object",
        "properties": {}
      }
    }
  ]
}

Quick Install

# Run via uvx from PyPI
uvx --from mcp-shellcheck shellcheck-mcp-server

# Run via uvx from GitHub release
uvx --from https://github.com/Ev3lynx727/mcp-shellcheck/releases/download/v0.1.3/mcp_shellcheck-0.1.3-py3-none-any.whl shellcheck-mcp-server

# One-liner install (install.sh)
curl -fsSL https://raw.githubusercontent.com/Ev3lynx727/mcp-shellcheck/main/install.sh | sh

# Install from PyPI
pip install mcp-shellcheck

# Clone and dev install
git clone https://github.com/Ev3lynx727/mcp-shellcheck.git
cd mcp-shellcheck && pip install -e .

Features

• File-based analysis: Check shell scripts by file path
• Inline script checking: Analyze raw shell script content directly
• Multiple shell support: bash, sh, dash, ksh, ash
• Configurable checks: Exclude specific warnings, set severity levels
• Structured output: JSON-formatted results for easy parsing
• OpenCode integration: Ready to use with OpenCode agents
• Production-ready: Async, tested, validated, logged

Requirements

• Python 3.10+
• ShellCheck installed on the system

Installing ShellCheck

Recommended (always latest):

pip install shellcheck-py

The shellcheck-py package provides a pre-built shellcheck v0.11.0 binary on your PATH with no system dependencies.

System package managers (may ship older versions):

# Ubuntu/Debian
sudo apt-get install shellcheck

# macOS
brew install shellcheck

# Fedora/RHEL
sudo dnf install ShellCheck

# Arch Linux
sudo pacman -S shellcheck

Tools

shellcheck

Run ShellCheck on a shell script to find bugs, stylistic issues, and potential errors.

Parameters:

Parameter	Type	Required	Description
file_path	string	No*	Path to the shell script file
script_content	string	No*	Raw shell script content
shell	string	No	Shell type: bash, sh, dash, ksh, ash (default: bash)
check_sourced	boolean	No	Enable checks for sourced files (default: false)
enable_all	boolean	No	Enable all optional checks (default: false)
exclude	string	No	Comma-separated codes to exclude (e.g., "SC1090,SC2148")
include	string	No	Comma-separated codes to include (e.g., "SC2086,SC2164")
severity	string	No	Minimum severity: error, warning, info, style

*Either file_path or script_content must be provided.

Common error codes:

Code	Description	Severity
SC1090	Can't follow non-constant source	info
SC2086	Double quote to prevent globbing	warning
SC2164	Use cd with || exit	warning
SC2006	Use $(...) instead of legacy backticks	style

shellcheck_info

Get ShellCheck version and server capabilities.

Parameters: None

Configuration

OpenCode

{
  "mcp": {
    "shellcheck": {
      "type": "local",
      "command": [
        "uv",
        "run",
        "--with", "mcp",
        "python3",
        "/path/to/mcp-shellcheck/shellcheck_mcp_server.py"
      ],
      "enabled": true,
      "timeout": 60000
    }
  }
}

OpenCode (uvx from GitHub release)

{
  "mcp": {
    "shellcheck": {
      "type": "local",
      "command": [
        "uvx",
        "--from", "https://github.com/Ev3lynx727/mcp-shellcheck/releases/download/v0.1.3/mcp_shellcheck-0.1.3-py3-none-any.whl",
        "shellcheck-mcp-server"
      ],
      "enabled": true,
      "timeout": 60000
    }
  }
}

Claude Desktop

{
  "mcpServers": {
    "shellcheck": {
      "command": "python3",
      "args": ["/path/to/mcp-shellcheck/shellcheck_mcp_server.py"]
    }
  }
}

Cursor

{
  "mcpServers": {
    "shellcheck": {
      "command": "uvx",
      "args": ["shellcheck-mcp-server"]
    }
  }
}

VS Code (Copilot)

Add to .vscode/mcp.json:

{
  "servers": {
    "shellcheck": {
      "command": "python3",
      "args": ["/path/to/mcp-shellcheck/shellcheck_mcp_server.py"]
    }
  }
}

Examples

Check a File

// Input
{ "file_path": "/path/to/deploy.sh" }

// Output
{
  "success": false,
  "message": "Found 3 issue(s)",
  "results": [
    {
      "line": 15,
      "column": 10,
      "code": "SC2086",
      "message": "Double quote to prevent globbing",
      "severity": "warning"
    }
  ],
  "exit_code": 1
}

Check Script Content

// Input
{ "script_content": "#!/bin/bash\ncat `ls *.txt`", "shell": "bash" }

Exclude Specific Warnings

{ "file_path": "/path/to/script.sh", "exclude": "SC1090,SC2148" }

Filter by Severity

{ "file_path": "/path/to/script.sh", "severity": "error" }

Troubleshooting

Problem	Solution
ShellCheck not found	Install via pip install shellcheck-py or system package manager
MCP package not installed	pip install mcp
Server not connecting	Verify shellcheck --version, test with python3 shellcheck_mcp_server.py
Timeout errors	Increase timeout: "timeout": 120000 in MCP config

Development

pip install -e ".[dev]"
pytest
ruff check .

See CHANGELOG.md for release history and ARCHITECTURE.md for design docs.

License

MIT