bash MCP server
2026년 10월 21일 커밋보안 WebSocket 커넥터를 통해 AI 어시스턴트가 로컬 머신에서 bash 명령어를 실행할 수 있도록 합니다.
다른 이름 assistant-core/mcp-bash
- 스타
- 0
- Tools
- 3
- 다운로드, 30일
- —
- 최신 버전
- —
- 마지막 커밋
- 2026년 10월 21일
- 라이선스
- MIT
bash MCP란?
보안 WebSocket 커넥터를 통해 AI 어시스턴트가 로컬 머신에서 bash 명령어를 실행할 수 있도록 합니다. 3개 도구를 제공합니다. 예: command, timeout_seconds, restart.
프로젝트 README에서 생성된 요약
bash MCP server 정보
mcp-bash는 Assistant Core를 사용하는 개발자가 AI 어시스턴트에서 터미널 명령어를 직접 실행할 수 있게 해줍니다. 이 서버는 WebSocket을 통해 외부로 연결을 시도하는 로컬 커넥터 역할을 하며, 공개 URL이나 개방된 포트 없이도 머신을 어시스턴트에 연결합니다. 모델이 명령어를 실행하고, 디렉토리를 관리하며, stdout 및 stderr와 같은 출력을 받을 수 있는 단일 bash 도구를 제공합니다.
설정하려면 Assistant Core 관리자가 제공한 특정 토큰과 URL을 사용하여 커넥터를 로컬에서 실행합니다. 도구 이름을 사용자 정의하거나 모바일 또는 웹 앱과 같이 bash 기능에 접근할 수 있는 인터페이스를 제한할 수 있습니다. 이 도구는 시스템을 수정할 수 있으므로 신뢰할 수 있는 어시스턴트와 함께 사용하도록 설계되었으며, 권한이 낮은 계정이나 rootless 컨테이너에서 실행하는 것이 가장 좋습니다.
보안은 특정 명령어 패턴을 허용, 확인 또는 차단할 수 있는 승인 시스템을 통해 관리됩니다. 또한 서버는 실행된 모든 명령어의 종료 코드와 실행 시간을 추적하기 위해 jsonl 형식의 감사 로그를 유지합니다.
활용 사례
- 1반복적인 터미널 작업 자동화개발자가 직접 타이핑하지 않고 AI에게 git status 또는 기타 빈번한 명령어를 실행하도록 지시할 수 있습니다.
- 2여러 대의 원격 머신 관리각 커넥터에 고유한 도구 이름을 할당하여 여러 대의 서로 다른 컴퓨터를 단일 어시스턴트에 연결할 수 있습니다.
- 3특정 환경 변수를 사용한 명령어 실행특정 작업에 필요한 경우에만 GitHub 토큰과 같은 민감한 자격 증명을 bash 도구에 전달할 수 있습니다.
- 4장시간 실행되는 연결 유지tmux를 사용하여 SSH 세션에서 연결을 끊은 후에도 bash 커넥터가 활성 상태를 유지하도록 할 수 있습니다.
프로젝트의 README를 바탕으로 작성되었습니다. 모든 활용 사례는 해당 내용의 인용문과 대조하여 확인합니다.
bash MCP 도구 3
README에서 감지됨commandtimeout_secondsrestart
| command | — | |
| timeout_seconds | — | |
| restart | — |
구성
BASH_TOOL_NAMELOCAL_CONNECTOR_TOKENLOCAL_CONNECTOR_URL
| 이름 | 설명 | 유형 |
|---|---|---|
| BASH_TOOL_NAME | — | |
| LOCAL_CONNECTOR_TOKEN | — | |
| LOCAL_CONNECTOR_URL | — |
자동 검사
2026년 11월 14일에 실행됨전체 보고서 →아직 인증되지 않았습니다. 서버는 80점 이상의 점수, 심각한 결함 없음, 그리고 검사에 충분한 데이터를 갖추어야 합니다. 검사 방식 · 점수를 높이기 위해 수정할 항목
- 소스 저장소 연결 및 접근 가능assistant-core/mcp-bash is public and reachablegithub.com/assistant-core/mcp-bash ↗통과
- 패키지가 이 저장소를 소스로 명시검사되지 않음
- 빌드 출처(Sigstore 증명)검사되지 않음
- 오픈 소스 라이선스 (OSI)MITspdx.org/licenses/MIT.html ↗통과
- 최근 1년 내 커밋 또는 릴리스Last commit or release 2026-10-21github.com/assistant-core/mcp-bash ↗통과
- OpenSSF Scorecard검사되지 않음
- 패키지 이름이 인기 패키지와 유사하지 않음검사되지 않음
- 패키지 및 해당 종속성에 중요한 보안 권고 없음검사되지 않음
- 모델에 대한 숨겨진 지침 없음3 tool descriptions and the README read; no override phrases, credential paths or hidden characters통과
- 파괴적인 도구에 라벨 표시됨No tool named like delete, drop or exec통과
- 원격 엔드포인트가 MCP 핸드셰이크에 응답검사되지 않음
README
GitHub에서 보기mcp-bash
A minimal MCP server that lets an AI assistant run bash commands on your machine, connected as an Assistant Core local connector. The connector dials out over WebSocket, so the machine needs no public URL or open port.
⚠️ Anyone who can chat with the connected assistant can run commands as your user. Use it only with assistants you trust, run it under a low-privilege account, and stop it when you are done.
Quick start
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
# Assistant Core admin → MCP → Local connector → Add connector (token shown once)
export LOCAL_CONNECTOR_URL="wss://api.assistantcore.com/local-connector/ws"
export LOCAL_CONNECTOR_TOKEN="lc_..."
python connector.py
Then click Refresh tools in the admin: the assistant gets one tool, bash. Assistant Core offers a connector's tools only as the owner last refreshed them, so refresh again after changing BASH_TOOL_NAME, BASH_SURFACES or the server.
You can also put both settings in a .env file (see .env.example). To connect a different stdio MCP server, pass its script: python connector.py my_server.py.
Where the tool is offered
On Assistant Core the tool is offered only in the web and mobile apps (BASH_SURFACES=app), never to website widget visitors, messaging apps, voice devices or the public API, where anyone the assistant talks to could run commands. To widen it, list the surfaces: BASH_SURFACES=app,api. The admin can narrow this further, not widen it.
When it asks first
Assistant Core asks before every command unless a rule says otherwise, because the tool can change anything on the machine. The tool tells Assistant Core which argument holds the command line, so rules can name commands instead of the whole tool:
- On an approval card, tick Don't ask again (for commands starting with
git status) to rungit statuswithout asking next time, in chat and in scheduled tasks. Manage these in Settings → Approvals. - The assistant's owner sets rules for everyone in the admin (Approvals): Allow
git status, Ask fordocker, Blockrm. Block wins over Ask, Ask over Allow.
A command line runs without asking only when every command in it is allowed: git status && rm -rf x still asks. Lines with $(…), backticks, redirections or variables, and commands that run other commands (sudo, bash -c, xargs, python…), are never allowed by a command rule.
After updating this server, refresh tools in the admin once so Assistant Core sees the new definition.
Several machines or several assistants
One assistant, several machines. Add a connector per machine in the admin, each with its own token, and give each machine its own tool name so the model can tell them apart:
# on web01, with web01's token
BASH_TOOL_NAME=web01_bash python connector.py
# on db01, with db01's token
BASH_TOOL_NAME=db01_bash python connector.py
Then refresh tools in the admin. A tool name belongs to the connector that offered it first: a second machine offering the same name is refused, and its log says so. Each token connects one machine at a time, and deleting or regenerating one disconnects only that machine.
One machine, several assistants. A connector token belongs to one assistant, so run one connector per assistant, each with its own token and audit log:
LOCAL_CONNECTOR_TOKEN=lc_AAA BASH_AUDIT_LOG=~/audit-a.jsonl python connector.py
LOCAL_CONNECTOR_TOKEN=lc_BBB BASH_AUDIT_LOG=~/audit-b.jsonl python connector.py
Everyone who can chat with any of those assistants can run commands on the machine.
Limit what commands can reach
The server only starts commands; it does not confine them. For anything beyond a personal machine:
- Run the connector as a dedicated user without
sudo, owning only the directories the assistant should touch. - Better, run it in a rootless container with a read-only root filesystem and one writable volume, and restrict its outbound network if you can: commands can send anything they read to the internet.
- Pass secrets with
BASH_PASS_ENVonly when a task needs them, and reviewaudit.jsonl.
Keep it running on a server
To keep the connector running after you close SSH, start it inside tmux:
tmux new -s connector
cd ~/mcp-bash && source .venv/bin/activate && python connector.py
# Ctrl+B then D to detach; the connector keeps running
tmux attach -t connector # back to the logs
tmux kill-session -t connector # stop it
tmux survives SSH disconnects, but not a server reboot, and nothing restarts the connector if it exits.
The bash tool
| Parameter | Description |
|---|---|
command |
Bash command to run |
timeout_seconds |
1–120, default 30 |
restart |
Start from BASH_WORKDIR instead of where the last command ended |
Returns stdout, stderr, exit_code, timed_out, truncated and cwd (where the command ended).
- The first command starts in
BASH_WORKDIR(default: your home directory); each later one starts where the previous one ended, like a terminal. Environment variables, aliases and functions do not carry over: every call is a new shell. A command that times out keeps the directory it started in. This is a starting point, not a sandbox. - Commands see only a minimal environment (
PATH,HOME,USER,SHELL, locale,TERM,TMPDIR,TZ), so secrets in your shell, including the connector token, never reach the assistant. Pass extra variables explicitly withBASH_PASS_ENV=GITHUB_TOKEN,AWS_PROFILE; anything you pass, the assistant can read. - stdin is closed, so commands that prompt for input fail instead of hanging.
- On timeout the whole process group is killed. A process that starts its own session (
setsid) can outlive it; there is no sandbox to stop that. - Background jobs keep running after the command returns; redirect their output (
cmd > log 2>&1 &), since the result is returned as soon as bash exits. - stdout and stderr are each truncated to 20,000 characters, keeping the first 8,000 and the last 12,000, and memory stays bounded however much a command prints.
- At most 2 commands run at once; extra calls return an error.
- Every command is appended to
audit.jsonlnext tobash_server.py(orBASH_AUDIT_LOG): time, command, starting directory, exit code and duration, not the output. The file is readable only by you. - Requires bash (macOS, Linux, or WSL on Windows).
Reconnection
connector.py reconnects with exponential backoff (1 s up to 10 min), and starts over after a session that stayed up for a minute. If the connector token is regenerated or deleted in the admin, the log says so; restart with the new token. If the relay refuses the connection because the token is already in use or another machine offers the same tool name, the log names the conflict.
Tests
pip install pytest && pytest -q
bash MCP 질문
bash MCP는 어떤 도구를 제공하나요?
3개 도구를 제공합니다. 예: command, timeout_seconds, restart.
이 서버를 통해 bash 명령어를 어떻게 실행하나요?
이 서버는 명령어 문자열, 선택 사항인 타임아웃, 작업 디렉토리를 결정하는 재시작 플래그를 받는 bash 도구를 제공합니다.
어시스턴트가 실행할 수 있는 명령어를 제한할 수 있나요?
네, Assistant Core 관리자가 특정 명령어를 허용(Allow), 확인(Ask) 또는 차단(Block)하도록 규칙을 설정할 수 있으며, 차단 설정이 우선 적용됩니다.
커넥터는 네트워크 연결을 어떻게 처리하나요?
커넥터는 WebSocket을 통해 외부로 연결을 시도하므로, 머신에 공개 URL이나 개방된 포트가 필요하지 않으며 재연결 시 지수 백오프(exponential backoff) 방식을 사용합니다.