MCP Server for controlled command execution with interactive approval system in trusted development environments
npm install utaba-community-shellA production-ready MCP (Model Context Protocol) server that gives Claude secure command-line access with browser-based approval system for safe AI-human collaboration.
šÆ Perfect for: Developers who want Claude to help with real development tasks
š”ļø Built-in Safety: Interactive approval workflow for risky commands
ā” Powerful: Full access to npm, git, build tools, and custom commands
Claude: "Let me run your tests"
``bash`
ā
npm test ā runs immediately (trusted command)
Claude: "Let me create a new React app"
`bash`
š”ļø npx create-react-app ā opens browser for approval
You: Click "Approve" in browser ā Command executes
---
bash
npm install -g utaba-community-shell
`$3
Find your Claude Desktop config file:
- Windows:
%APPDATA%\Claude\claude_desktop_config.json
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Linux: ~/.config/claude/claude_desktop_config.json$3
Simple Setup (Windows):
`json
{
"mcpServers": {
"mcp-shell": {
"command": "npx",
"args": ["utaba-community-shell"],
"env": {
"MCP_SHELL_START_DIRECTORY": "C:\\Users\\YourName\\my-project"
}
}
}
}
`Simple Setup (macOS/Linux):
`json
{
"mcpServers": {
"mcp-shell": {
"command": "npx",
"args": ["utaba-community-shell"],
"env": {
"MCP_SHELL_START_DIRECTORY": "/Users/yourname/my-project"
}
}
}
}
`$3
That's it! Claude now has secure command-line access.
---
šÆ What Claude Can Do
$3
- Package Management: npm install, npm test, npm run build
- Version Control: git status, git add, git commit, git push
- TypeScript: tsc --build, tsc --noEmit
- Code Quality: eslint, prettier$3
- Package Execution: npx create-react-app, npx playwright install
- Network Requests: curl, wget
- Custom risky commands: Anything you configure with requiresConfirmation: true---
š”ļø Interactive Approval System
When Claude tries to run a risky command:
1. š Browser Opens Automatically ā Secure approval interface
2. š Command Review ā See exactly what will run, where, and why it might be risky
3. ā
Your Decision ā Approve or reject with full context
4. ā” Instant Execution ā Command runs immediately after approval
$3
`
š”ļø Command Approval Center
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāCommand Execution Request Risk: 7/10
npx create-react-app my-new-project
Working Directory: /Users/you/projects
Package: create-react-app
Timeout: 300s
ā ļø Risk Factors:
⢠Downloads and executes remote code
⢠Creates new files and directories
⢠Installs multiple dependencies
[ā
Approve] [ā Reject]
`---
āļø Configuration Examples
$3
Create mcp-shell-config.json in your project:`json
{
"projectRoots": ["/path/to/your/project"],
"trustedEnvironment": true,
"allowedCommands": [
{
"command": "npm",
"allowedArgs": ["install", "test", "run", "build"],
"description": "Package manager - runs immediately"
},
{
"command": "git",
"allowedArgs": ["status", "add", "commit", "push", "pull"],
"description": "Version control - runs immediately"
}
]
}
`Note: In windows your paths should include double backslashes, eg; "C:\\Users\\MyProfile\\Repos\\MyProject"
$3
For comprehensive development environment:`json
{
"description": "Full development environment with approval system",
"projectRoots": ["/Users/yourname/projects"],
"trustedEnvironment": true,
"maxConcurrentCommands": 5,
"defaultTimeout": 120000,
"allowedCommands": [
{
"command": "npm",
"description": "Node.js package manager",
"allowedArgs": ["install", "run", "test", "build", "start", "audit", "outdated"],
"timeout": 300000,
"workingDirRestriction": "project-only",
"requiresConfirmation": false
},
{
"command": "npx",
"description": "Execute npm packages - REQUIRES APPROVAL",
"allowedArgs": "*",
"timeout": 600000,
"workingDirRestriction": "project-only",
"requiresConfirmation": true
},
{
"command": "git",
"description": "Git version control",
"allowedArgs": ["status", "add", "commit", "push", "pull", "fetch", "checkout", "branch", "log", "diff", "-F"],
"timeout": 120000,
"workingDirRestriction": "project-only",
"requiresConfirmation": false
},
{
"command": "tsc",
"description": "TypeScript compiler",
"allowedArgs": ["--build", "--watch", "--noEmit", "--listFiles", "--project"],
"timeout": 180000,
"workingDirRestriction": "project-only",
"requiresConfirmation": false
},
{
"command": "eslint",
"description": "ESLint linter",
"allowedArgs": ["--fix", "--cache", "--ext", "--format"],
"argPatterns": [
"^--ext\\s+\\.(js|ts|jsx|tsx)(,\\.(js|ts|jsx|tsx))*$",
"^\\./", "^src/", "^\\\\/\\*\\.(js|ts|jsx|tsx)$"
],
"timeout": 90000,
"workingDirRestriction": "project-only",
"requiresConfirmation": false
},
{
"command": "curl",
"description": "HTTP client - REQUIRES APPROVAL",
"argPatterns": ["^(https?|ftp):\/\/[^\\s/$.?#].[^\\s]*$"],
"timeout": 60000,
"workingDirRestriction": "none",
"requiresConfirmation": true
}
],
"logLevel": "info",
"logToFile": false
}
`---
š§ Environment Variables
| Variable | Description | Example |
|----------|-------------|---------|
|
MCP_SHELL_START_DIRECTORY | Required: Project root directory | /Users/you/my-project |
| MCP_SHELL_CONFIG_PATH | Custom config file location | ./my-config.json |
| LOG_LEVEL | Logging detail: debug, info, warn, error | info |
| LOG_FILE | Enable file logging | ./mcp-shell.log |
| MCP_SHELL_MAX_CONCURRENT | Max simultaneous commands | 3 |---
šØ Security Model
$3
- ā
Use only in development environments you trust
- ā
npm commands have full system access (this is npm's design, not a limitation)
- ā
Command whitelisting prevents accidents, approval system adds human oversight
- ā
Perfect for AI-human collaboration with appropriate safeguards$3
- Command Validation: Only whitelisted commands can run
- Argument Checking: Parameters validated against safe patterns
- Directory Restrictions: Commands limited to project directories
- Human Oversight: Interactive approval for risky operations
- Audit Logging: Complete history of all commands$3
Configure any command with requiresConfirmation: true:
- External package execution (npx)
- Network requests (curl, wget)
- System modifications (custom admin commands)
- File operations outside project (if configured)---
š” Real-World Examples
$3
`bash
Claude will request approval for:
npx create-react-app my-awesome-appAfter your approval:
ā
Project created
ā
Dependencies installed
ā
Ready for development
`$3
`bash
These run immediately (trusted):
npm test ā
git status ā
Results displayed in real-time
`$3
`bash
Trusted commands run immediately:
git add . ā
git commit -m "Deploy updates" ā
git push ā
If you configured deployment commands to require approval:
npm run deploy š”ļø ā browser approval ā ā
`---
š ļø Advanced Features
$3
See command output as it happens:
`bash
npm install # Long running command
š Installing dependencies... 47% complete
š Building native modules...
š ā
Completed in 23.4s
`$3
- Monitor active commands: See what's running and for how long
- Kill hanging processes: Stop commands that get stuck
- Execution history: Review past commands with timing data$3
`bash
Enable detailed logging
LOG_LEVEL="info" LOG_FILE="./mcp-shell.log"
`$3
Track approval patterns:
- Decision history: See what you've approved/rejected
- Risk assessment: Understand why commands are flagged
- Performance metrics: Average approval time, success rates---
š Troubleshooting
$3
- Check default browser settings
- Try manually visiting the approval URL shown in Claude's response
- Ensure localhost connections aren't blocked$3
- Verify the command is in your allowedCommands config
- Check that arguments match the allowedArgs or argPatterns
- Ensure the command exists on your system$3
- Confirm directory is within your projectRoots
- Check MCP_SHELL_START_DIRECTORY points to correct location
- Verify directory permissions$3
- Default approval timeout is 5 minutes
- Check if browser window closed accidentally
- Verify approval server is still running---
šÆ Best Practices
$3
- ā
Review approval requests carefully - understand what will be executed
- ā
Use project-specific configs - tailor permissions to each project
- ā
Enable logging - track command history for debugging
- ā
Regular config reviews - ensure permissions match current needs$3
- ā
Set appropriate timeouts - longer for build commands, shorter for quick operations
- ā
Limit concurrent commands - prevent system overload
- ā
Use streaming for long operations - better user experience$3
- ā
Start with restrictive config - add permissions as needed
- ā
Test approval workflow - ensure browser integration works
- ā
Document custom commands - help team understand permissions---
š What's New in This Version
$3
- Browser-based approval interface with risk assessment
- Real-time updates via Server-Sent Events
- Keyboard shortcuts for faster decisions
- Mobile-friendly responsive design$3
- Async job queue for long-running commands
- Real-time output streaming with progress indicators
- Process management with kill capabilities
- Comprehensive logging with rotation support$3
- Template-based setup for common development stacks
- Environment variable overrides for easy customization
- Validation and error reporting for configuration issues---
š¤ Contributing
We welcome contributions! Areas of focus:
- Risk assessment improvements - better command risk scoring
- UI enhancements - approval interface improvements
- New command templates - support for more development tools
- Security features - additional validation and protection
š License
BSD-3-Clause License - see LICENSE file for details.
š Credits
Built by Tim Wheeler in collaboration with Claude (Anthropic).
From the Utaba AI open source community.
---
Ready to give Claude secure command-line superpowers?
`bash
npm install -g utaba-community-shell
``Happy AI-powered development! šš¤āØ