mcp-shell 🐚

mcp-shell

シェルコマンドを実行する MCP サーバーです。LLM にはツールを提供し、何をどのように実行するかはユーザーが制御できます。

mark3labs/mcp-go を基盤としています。Go で記述されています。

---

実行方法

Docker（最も簡単）：

docker run -it --rm -v /tmp/mcp-workspace:/tmp/mcp-workspace sonirico/mcp-shell:latest

ソースから：

git clone https://github.com/sonirico/mcp-shell && cd mcp-shell
make install
mcp-shell

---

設定方法

デフォルトではセキュアモードです。 設定ファイルがない場合、mcp-shell はセキュアモードで起動し、型付きツールのみを登録します。型付きツールには、ファイルの読み取り、grep／glob、git の調査、および（オプトインで有効にする）ファイル／git の書き込みと、オペレーター定義のスクリプトが含まれます。生のシェルコマンドはありません。以下のデフォルト設定を変更する場合にのみ、設定ファイルが必要です。制限を完全になくして実行するには、明示的にオプトインする必要があります。

MCP_SHELL_ALLOW_UNSAFE=1 mcp-shell   # disables secure mode; the only tool is shell_exec

ポリシーをカスタマイズするには、YAML 設定ファイルを指定します。

export MCP_SHELL_SEC_CONFIG_FILE=/path/to/security.yaml
mcp-shell

セキュアモード（デフォルト）— 型付きツールのみを使用し、すべてのパスを working_directory 内に制限します。

security:
  enabled: true
  working_directory: /tmp/mcp-workspace
  max_execution_time: 30s
  max_output_size: 1048576
  run_as_user: ""
  audit_log: true

  # Expose file and git write tools (write_file, edit_file, mkdir, move,
  # delete, git_add, git_commit, git_switch, git_restore, git_stash). Off by
  # default.
  writes_enabled: false

  # Operator-defined scripts exposed through the run_script tool. The client
  # picks a name; the argv is yours and cannot be altered.
  # scripts:
  #   test: ["go", "test", "./..."]
  #   lint: ["golangci-lint", "run"]

---

接続方法

Claude Desktop — MCP 設定に追加します。

{
  "mcpServers": {
    "shell": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "sonirico/mcp-shell:latest"],
      "env": { "MCP_SHELL_LOG_LEVEL": "info" }
    }
  }
}

カスタム設定の場合は、ファイルをマウントして環境変数を設定します。

{
  "command": "docker",
  "args": ["run", "--rm", "-i", "-v", "/path/to/security.yaml:/etc/mcp-shell/security.yaml", "-e", "MCP_SHELL_SEC_CONFIG_FILE=/etc/mcp-shell/security.yaml", "sonirico/mcp-shell:latest"]
}

---

ツール

セキュアモード（デフォルト）では、以下の型付きツールが登録されます。* は必須パラメーターを示します。

ツール	パラメーター	利用可能な条件
read_file	path*, offset, limit, tail	常時
list_dir	path, depth, include_hidden	常時
glob	pattern*, path, newer_than, max_results	常時
grep	pattern*, path, glob, ignore_case, context, files_only, count, max_results	常時
stat	path*	常時
diff_files	path_a*, path_b*	常時
system_info		常時
git_status		常時
git_log	max_count, ref, path, author, grep, since, until, oneline, follow	常時
git_diff	ref, ref_to, staged, path, stat_only, name_only	常時
git_show	ref, path, stat_only	常時
git_blame	path*, ref, line_start, line_end	常時
git_branches	all, merged	常時
git_tags	pattern	常時
git_rev_parse	ref*	常時
git_ls_files	path, untracked	常時
git_stash_list		常時
git_remotes		常時
write_file	path*, content*, append	writes_enabled
edit_file	path*, old_string*, new_string*, replace_all	writes_enabled
mkdir	path*	writes_enabled
move	from*, to*	writes_enabled
delete	path*, recursive	writes_enabled
git_add	paths, all	writes_enabled
git_commit	message*, all	writes_enabled
git_switch	branch*, create	writes_enabled
git_restore	paths*, staged	writes_enabled
git_stash	action*, message	writes_enabled
run_script	name*	scripts

すべてのパスパラメーターは working_directory を基準に解決されます（シンボリックリンクはたどります）。その範囲外のパスは拒否されます。Git のパスと参照は位置引数として渡され、検証されます。- で始まる参照は拒否されます。ネットワークツールはありません。push、fetch、clone は提供されません。

制限なしモード：shell_exec は MCP_SHELL_ALLOW_UNSAFE=1 の場合にのみ利用できます。設計上、検証を行わずに bash -c でコマンドを実行します。このモードで登録されるツールはこれだけです。

---

環境変数

変数	説明
MCP_SHELL_SEC_CONFIG_FILE	セキュリティ YAML のパス（組み込みのセキュアなデフォルト設定を上書きします）
MCP_SHELL_ALLOW_UNSAFE	1（または true）を設定すると、セキュアモードを無効にし、型付きツールの代わりに shell_exec を公開します（オプトイン）
MCP_SHELL_SERVER_NAME	サーバー名（デフォルト："mcp-shell 🐚"）
MCP_SHELL_LOG_LEVEL	debug、info、warn、error、fatal
MCP_SHELL_LOG_FORMAT	json、console
MCP_SHELL_LOG_OUTPUT	stdout、stderr、file

---

開発

make install dev-tools   # deps + goimports, golines
make fmt test lint
make docker-build       # build image locally
make release            # binary + docker image

---

セキュリティ

• デフォルト：セキュアモードです。サーバーが各コマンドの argv をすべて組み立て、クライアントがシェル文字列を渡すことはありません。型付きツールのみが登録されます。
• パスの制限：すべてのパスパラメーターは working_directory を基準に解決され、シンボリックリンクもたどります。解決先が working_directory の外になるパスは拒否されます。
• Git の強化：パスは -- の後に、参照は --end-of-options の後に渡され、- で始まる参照は拒否されます。Git は GIT_CONFIG_NOSYSTEM=1、GIT_CONFIG_GLOBAL=/dev/null を設定し、core.fsmonitor、core.pager、core.hooksPath を無効化したうえで、log/diff/show/blame に --no-ext-diff --no-textconv を指定して実行されます。
• 最小限の環境：子プロセスに渡されるのは PATH、HOME、LANG のみで、サーバー自身の環境変数や .env のシークレットは渡されません。
• 書き込みとスクリプトはオプトイン：writes_enabled: true にするとファイル／Git の書き込みツールが利用可能になり、空でない scripts マップを設定すると run_script が利用可能になります。どちらもデフォルトでは無効です。
• 無制限モード：MCP_SHELL_ALLOW_UNSAFE=1 を設定した場合に限られます。登録されるツールは shell_exec のみで、検証なしに bash -c を実行します。ローカル開発には適していますが、それ以外では危険です。
• Docker：root 以外のユーザーで実行される、Alpine ベースのイメージです。本番環境で使用してください。多層防御として、OS サンドボックス（読み取り専用 FS、ケーパビリティの削除）との併用が最適です。

脅威モデル、保証内容、脆弱性報告の対象範囲については SECURITY.md をご覧ください。アドバイザリを提出する前にお読みください。

---

0.x からの移行

セキュアモードでは shell_exec のコマンド文字列を検証しなくなり、代わりに型付きツールを公開します。設定ファイルの security: ブロックでは、次のキーを受け付けなくなりました。

削除されたキー	置き換え
use_shell_execution	不要です。型付きツールはシェルを実行しません
allowed_executables	不要です。各ツールはサーバーが組み立てた固定の argv を実行します
allowed_commands	不要です。上記と同じです
blocked_commands	不要です。上記と同じです
blocked_patterns	不要です。上記と同じです

これらのキーのいずれかを設定したまま設定ファイルを読み込むと、キー名を含むエラーが発生して起動に失敗します。「レガシーモード」はなくなり、security-legacy.yaml のサンプルもありません。生のシェルアクセスが必要な場合は、MCP_SHELL_ALLOW_UNSAFE=1 を設定すると shell_exec が再び利用可能になります。このツールは、もはや security: ブロックによる制限を一切受けません。

---

貢献

フォークしてブランチを作成し、make fmt test を実行してから、PR を作成してください。