{"id":23479546,"url":"https://github.com/tumf/mcp-shell-server","last_synced_at":"2025-03-05T05:28:13.273Z","repository":{"id":267462788,"uuid":"901328207","full_name":"tumf/mcp-shell-server","owner":"tumf","description":null,"archived":false,"fork":false,"pushed_at":"2025-01-05T01:04:54.000Z","size":179,"stargazers_count":21,"open_issues_count":3,"forks_count":8,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-02-27T21:36:02.164Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tumf.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-12-10T13:09:04.000Z","updated_at":"2025-02-26T15:15:58.000Z","dependencies_parsed_at":"2024-12-29T07:15:28.145Z","dependency_job_id":null,"html_url":"https://github.com/tumf/mcp-shell-server","commit_stats":null,"previous_names":["tumf/mcp-shell-server"],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tumf%2Fmcp-shell-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tumf%2Fmcp-shell-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tumf%2Fmcp-shell-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tumf%2Fmcp-shell-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tumf","download_url":"https://codeload.github.com/tumf/mcp-shell-server/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241971745,"owners_count":20050931,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-24T19:30:12.200Z","updated_at":"2025-03-05T05:28:13.265Z","avatar_url":"https://github.com/tumf.png","language":"Python","readme":"# MCP Shell Server\n\n[![codecov](https://codecov.io/gh/tumf/mcp-shell-server/branch/main/graph/badge.svg)](https://codecov.io/gh/tumf/mcp-shell-server)\n\nA secure shell command execution server implementing the Model Context Protocol (MCP). This server allows remote execution of whitelisted shell commands with support for stdin input.\n\n## Features\n\n* **Secure Command Execution**: Only whitelisted commands can be executed\n* **Standard Input Support**: Pass input to commands via stdin\n* **Comprehensive Output**: Returns stdout, stderr, exit status, and execution time\n* **Shell Operator Safety**: Validates commands after shell operators (; , \u0026\u0026, ||, |)\n* **Timeout Control**: Set maximum execution time for commands\n\n## MCP client setting in your Claude.app\n\n### Published version\n\n```shell\ncode ~/Library/Application\\ Support/Claude/claude_desktop_config.json\n```\n\n```json\n{\n  \"mcpServers\": {\n    \"shell\": {\n      \"command\": \"uvx\",\n      \"args\": [\n        \"mcp-shell-server\"\n      ],\n      \"env\": {\n        \"ALLOW_COMMANDS\": \"ls,cat,pwd,grep,wc,touch,find\"\n      }\n    },\n  }\n}\n```\n\n### Local version\n\n#### Configuration\n\n```shell\ncode ~/Library/Application\\ Support/Claude/claude_desktop_config.json\n```\n\n```json\n{\n  \"mcpServers\": {\n    \"shell\": {\n      \"command\": \"uv\",\n      \"args\": [\n        \"--directory\",\n        \".\",\n        \"run\",\n        \"mcp-shell-server\"\n      ],\n      \"env\": {\n        \"ALLOW_COMMANDS\": \"ls,cat,pwd,grep,wc,touch,find\"\n      }\n    },\n  }\n}\n```\n\n#### Installation\n\n```bash\npip install mcp-shell-server\n```\n\n## Usage\n\n### Starting the Server\n\n```bash\nALLOW_COMMANDS=\"ls,cat,echo\" uvx mcp-shell-server\n# Or using the alias\nALLOWED_COMMANDS=\"ls,cat,echo\" uvx mcp-shell-server\n```\n\nThe `ALLOW_COMMANDS` (or its alias `ALLOWED_COMMANDS` ) environment variable specifies which commands are allowed to be executed. Commands can be separated by commas with optional spaces around them.\n\nValid formats for ALLOW_COMMANDS or ALLOWED_COMMANDS:\n\n```bash\nALLOW_COMMANDS=\"ls,cat,echo\"          # Basic format\nALLOWED_COMMANDS=\"ls ,echo, cat\"      # With spaces (using alias)\nALLOW_COMMANDS=\"ls,  cat  , echo\"     # Multiple spaces\n```\n\n### Request Format\n\n```python\n# Basic command execution\n{\n    \"command\": [\"ls\", \"-l\", \"/tmp\"]\n}\n\n# Command with stdin input\n{\n    \"command\": [\"cat\"],\n    \"stdin\": \"Hello, World!\"\n}\n\n# Command with timeout\n{\n    \"command\": [\"long-running-process\"],\n    \"timeout\": 30  # Maximum execution time in seconds\n}\n\n# Command with working directory and timeout\n{\n    \"command\": [\"grep\", \"-r\", \"pattern\"],\n    \"directory\": \"/path/to/search\",\n    \"timeout\": 60\n}\n```\n\n### Response Format\n\nSuccessful response:\n\n```json\n{\n    \"stdout\": \"command output\",\n    \"stderr\": \"\",\n    \"status\": 0,\n    \"execution_time\": 0.123\n}\n```\n\nError response:\n\n```json\n{\n    \"error\": \"Command not allowed: rm\",\n    \"status\": 1,\n    \"stdout\": \"\",\n    \"stderr\": \"Command not allowed: rm\",\n    \"execution_time\": 0\n}\n```\n\n## Security\n\nThe server implements several security measures:\n\n1. **Command Whitelisting**: Only explicitly allowed commands can be executed\n2. **Shell Operator Validation**: Commands after shell operators (;, \u0026\u0026, ||, |) are also validated against the whitelist\n3. **No Shell Injection**: Commands are executed directly without shell interpretation\n\n## Development\n\n### Setting up Development Environment\n\n1. Clone the repository\n\n```bash\ngit clone https://github.com/yourusername/mcp-shell-server.git\ncd mcp-shell-server\n```\n\n2. Install dependencies including test requirements\n\n```bash\npip install -e \".[test]\"\n```\n\n### Running Tests\n\n```bash\npytest\n```\n\n## API Reference\n\n### Request Arguments\n\n| Field     | Type       | Required | Description                                   |\n|-----------|------------|----------|-----------------------------------------------|\n| command   | string[]   | Yes      | Command and its arguments as array elements   |\n| stdin     | string     | No       | Input to be passed to the command            |\n| directory | string     | No       | Working directory for command execution       |\n| timeout   | integer    | No       | Maximum execution time in seconds             |\n\n### Response Fields\n\n| Field           | Type    | Description                                |\n|----------------|---------|---------------------------------------------|\n| stdout         | string  | Standard output from the command           |\n| stderr         | string  | Standard error output from the command     |\n| status         | integer | Exit status code                           |\n| execution_time | float   | Time taken to execute (in seconds)         |\n| error          | string  | Error message (only present if failed)     |\n\n## Requirements\n\n* Python 3.11 or higher\n* mcp\u003e=1.1.0\n\n## License\n\nMIT License - See LICENSE file for details\n","funding_links":[],"categories":["CLI Tools","Code Execution \u0026 Automation MCP Servers","Cloud Infrastructure","Command Line","📚 Projects (1974 total)","MCP 服务器精选列表","Legend","🤖 AI/ML","サーバー実装","Security","MCP Servers","💻 Operating Systems \u0026 Command Line","Uncategorized","Table of Contents"],"sub_categories":["Playwright","🖥️ Command Line","MCP Servers","🖥️ 命令行与 Shell 交互","🖥️ \u003ca name=\"command-line\"\u003e\u003c/a\u003eCommand Line","🖥️ \u003ca name=\"command-line\"\u003e\u003c/a\u003eコマンドライン","How to Submit","Uncategorized","System Automation"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftumf%2Fmcp-shell-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftumf%2Fmcp-shell-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftumf%2Fmcp-shell-server/lists"}