mseep-cmd-line-mcp 0.5.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 [Your Name]
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,347 @@
1
+ Metadata-Version: 2.4
2
+ Name: mseep-cmd-line-mcp
3
+ Version: 0.5.0
4
+ Summary: Command-line MCP server for safe command execution
5
+ Home-page:
6
+ Author: mseep
7
+ Author-email: Your Name <your.email@example.com>
8
+ License: MIT
9
+ Classifier: Programming Language :: Python :: 3
10
+ Classifier: Programming Language :: Python :: 3.9
11
+ Classifier: Programming Language :: Python :: 3.10
12
+ Classifier: Programming Language :: Python :: 3.11
13
+ Classifier: Programming Language :: Python :: 3.12
14
+ Classifier: License :: OSI Approved :: MIT License
15
+ Classifier: Operating System :: OS Independent
16
+ Requires-Python: >=3.6
17
+ Description-Content-Type: text/markdown
18
+ License-File: LICENSE
19
+ Requires-Dist: mcp>=1.6.0
20
+ Provides-Extra: dev
21
+ Requires-Dist: pytest>=7.0.0; extra == "dev"
22
+ Requires-Dist: pytest-asyncio>=0.18.0; extra == "dev"
23
+ Requires-Dist: flake8>=4.0.0; extra == "dev"
24
+ Requires-Dist: black>=22.0.0; extra == "dev"
25
+ Dynamic: author
26
+ Dynamic: license-file
27
+ Dynamic: requires-python
28
+
29
+ # Command-Line MCP Server
30
+
31
+ [![PyPI version](https://badge.fury.io/py/cmd-line-mcp.svg)](https://badge.fury.io/py/cmd-line-mcp)
32
+ [![Python Versions](https://img.shields.io/pypi/pyversions/cmd-line-mcp.svg)](https://pypi.org/project/cmd-line-mcp/)
33
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
34
+
35
+ A secure Model Control Protocol (MCP) server that allows AI assistants to execute terminal commands with controlled directory access and command permissions.
36
+
37
+ ## Overview
38
+
39
+ Command-Line MCP provides a security layer between AI assistants and your terminal. It implements a dual security model:
40
+
41
+ 1. **Command Permissions**: Commands are categorized as read (safe), write (changes data), or system (affects system state), with different approval requirements
42
+ 2. **Directory Permissions**: Commands can only access explicitly whitelisted directories or directories approved during a session
43
+
44
+ AI assistants interact with this server using standardized MCP tools, enabling safe terminal command execution while preventing access to sensitive files or dangerous operations. You can configure the security level from highly restrictive to more permissive based on your needs.
45
+
46
+ ## Key Features
47
+
48
+ | Security | Usability | Integration |
49
+ |----------|-----------|-------------|
50
+ | Directory whitelisting | Command categorization (read/write/system) | Claude Desktop compatibility |
51
+ | Command filtering | Persistent session permissions | Standard MCP protocol |
52
+ | Pattern matching | Command chaining (pipes, etc.) | Auto-approval options |
53
+ | Dangerous command blocking | Intuitive approval workflow | Multiple config methods |
54
+
55
+ ## Supported Commands (out of the box)
56
+
57
+ ### Read Commands
58
+ - `ls`, `pwd`, `cat`, `less`, `head`, `tail`, `grep`, `find`, `which`, `du`, `df`, `file`, `sort`, etc.
59
+
60
+ ### Write Commands
61
+ - `cp`, `mv`, `rm`, `mkdir`, `rmdir`, `touch`, `chmod`, `chown`, etc.
62
+
63
+ ### System Commands
64
+ - `ps`, `top`, `htop`, `who`, `netstat`, `ifconfig`, `ping`, etc.
65
+
66
+ ## Security Architecture
67
+
68
+ The system implements a multi-layered security approach:
69
+
70
+ ```
71
+ ┌───────────────────────────────────────────────────────────────┐
72
+ │ COMMAND-LINE MCP SERVER │
73
+ ├──────────────────┬────────────────────────┬───────────────────┤
74
+ │ COMMAND SECURITY │ DIRECTORY SECURITY │ SESSION SECURITY │
75
+ ├──────────────────┼────────────────────────┼───────────────────┤
76
+ │ ✓ Read commands │ ✓ Directory whitelist │ ✓ Session IDs │
77
+ │ ✓ Write commands │ ✓ Runtime approvals │ ✓ Persistent │
78
+ │ ✓ System commands│ ✓ Path validation │ permissions │
79
+ │ ✓ Blocked list │ ✓ Home dir expansion │ ✓ Auto timeouts │
80
+ │ ✓ Pattern filters│ ✓ Subdirectory check │ ✓ Desktop mode │
81
+ └──────────────────┴────────────────────────┴───────────────────┘
82
+ ```
83
+
84
+ All security features can be configured from restrictive to permissive based on your threat model and convenience requirements.
85
+
86
+ ## Quick Start
87
+
88
+ ```bash
89
+ # Install
90
+ git clone https://github.com/yourusername/cmd-line-mcp.git
91
+ cd cmd-line-mcp
92
+ python -m venv venv
93
+ source venv/bin/activate
94
+ pip install -e .
95
+ cp config.json.example config.json
96
+
97
+ # Run
98
+ cmd-line-mcp # With default config
99
+ cmd-line-mcp --config config.json # With specific config
100
+ ```
101
+
102
+ ### Configuration Options
103
+
104
+ The server supports four configuration methods in order of precedence:
105
+
106
+ 1. **Built-in default configuration** (default_config.json)
107
+ 2. **JSON configuration file** (recommended for customization)
108
+ ```bash
109
+ cmd-line-mcp --config config.json
110
+ ```
111
+ 3. **Environment variables** (for specific overrides)
112
+ ```bash
113
+ export CMD_LINE_MCP_SECURITY_WHITELISTED_DIRECTORIES="~,/tmp"
114
+ ```
115
+ 4. **.env file** (for environment-specific settings)
116
+ ```bash
117
+ cmd-line-mcp --config config.json --env .env
118
+ ```
119
+
120
+ The default configuration is stored in `default_config.json` and is included with the package. You can copy this file to create your own custom configuration.
121
+
122
+ #### Core Configuration Settings
123
+
124
+ ```json
125
+ {
126
+ "security": {
127
+ "whitelisted_directories": ["/home", "/tmp", "~"],
128
+ "auto_approve_directories_in_desktop_mode": false,
129
+ "require_session_id": false,
130
+ "allow_command_separators": true
131
+ },
132
+ "commands": {
133
+ "read": ["ls", "cat", "grep"],
134
+ "write": ["touch", "mkdir", "rm"],
135
+ "system": ["ps", "ping"]
136
+ }
137
+ }
138
+ ```
139
+
140
+ #### Environment Variable Format
141
+
142
+ Environment variables use a predictable naming pattern:
143
+ ```
144
+ CMD_LINE_MCP_<SECTION>_<SETTING>
145
+ ```
146
+
147
+ Examples:
148
+ ```bash
149
+ # Security settings
150
+ export CMD_LINE_MCP_SECURITY_WHITELISTED_DIRECTORIES="/projects,/var/data"
151
+ export CMD_LINE_MCP_SECURITY_AUTO_APPROVE_DIRECTORIES_IN_DESKTOP_MODE=true
152
+
153
+ # Command additions (these merge with defaults)
154
+ export CMD_LINE_MCP_COMMANDS_READ="awk,jq,wc"
155
+ ```
156
+
157
+ ### Claude Desktop Integration
158
+
159
+ #### Setup
160
+
161
+ 1. Install [Claude for Desktop](https://claude.ai/download)
162
+ 2. Configure in `~/Library/Application Support/Claude/claude_desktop_config.json`:
163
+
164
+ ```json
165
+ {
166
+ "mcpServers": {
167
+ "cmd-line": {
168
+ "command": "/path/to/venv/bin/cmd-line-mcp",
169
+ "args": ["--config", "/path/to/config.json"],
170
+ "env": {
171
+ "CMD_LINE_MCP_SECURITY_REQUIRE_SESSION_ID": "false",
172
+ "CMD_LINE_MCP_SECURITY_AUTO_APPROVE_DIRECTORIES_IN_DESKTOP_MODE": "true"
173
+ }
174
+ }
175
+ }
176
+ }
177
+ ```
178
+
179
+ #### Recommended Claude Desktop Settings
180
+
181
+ For best experience, configure:
182
+ - `require_session_id: false` - Essential to prevent approval loops
183
+ - `auto_approve_directories_in_desktop_mode: true` - Optional for convenient access
184
+ - Include common directories in your whitelist
185
+
186
+ After configuration, restart Claude for Desktop.
187
+
188
+ ## AI Assistant Tools
189
+
190
+ The server provides these MCP tools for AI assistants:
191
+
192
+ | Tool | Purpose | Needs Approval |
193
+ |------|---------|----------------|
194
+ | `execute_command` | Run any command type | Yes, for write/system commands |
195
+ | `execute_read_command` | Run read-only commands | Directory approval only |
196
+ | `approve_directory` | Grant access to a directory | N/A - it's an approval tool |
197
+ | `approve_command_type` | Grant permission for command category | N/A - it's an approval tool |
198
+ | `list_directories` | Show authorized directories | No |
199
+ | `list_available_commands` | Show command categories | No |
200
+ | `get_command_help` | Get command usage guidance | No |
201
+ | `get_configuration` | View current settings | No |
202
+
203
+ ### Tool Examples
204
+
205
+ #### Directory Management
206
+
207
+ ```python
208
+ # Check available directories
209
+ dirs = await list_directories(session_id="session123")
210
+ whitelisted = dirs["whitelisted_directories"]
211
+ approved = dirs["session_approved_directories"]
212
+
213
+ # Request permission for a directory
214
+ if "/projects/my-data" not in whitelisted and "/projects/my-data" not in approved:
215
+ result = await approve_directory(
216
+ directory="/projects/my-data",
217
+ session_id="session123"
218
+ )
219
+ ```
220
+
221
+ #### Command Execution
222
+
223
+ ```python
224
+ # Read commands (read permissions enforced)
225
+ result = await execute_read_command("ls -la ~/Documents")
226
+
227
+ # Any command type (may require command type approval)
228
+ result = await execute_command(
229
+ command="mkdir -p ~/Projects/new-folder",
230
+ session_id="session123"
231
+ )
232
+ ```
233
+
234
+ #### Get Configuration
235
+
236
+ ```python
237
+ # Check current settings
238
+ config = await get_configuration()
239
+ whitelist = config["directory_whitelisting"]["whitelisted_directories"]
240
+ ```
241
+
242
+
243
+ ## Directory Security System
244
+
245
+ The server restricts command execution to specific directories, preventing access to sensitive files.
246
+
247
+ ### Directory Security Modes
248
+
249
+ The system supports three security modes:
250
+
251
+ | Mode | Description | Best For | Configuration |
252
+ |------|-------------|----------|--------------|
253
+ | **Strict** | Only whitelisted directories allowed | Maximum security | `auto_approve_directories_in_desktop_mode: false` |
254
+ | **Approval** | Non-whitelisted directories require explicit approval | Interactive use | Default behavior for standard clients |
255
+ | **Auto-approve** | Auto-approves directories for Claude Desktop | Convenience | `auto_approve_directories_in_desktop_mode: true` |
256
+
257
+ ### Whitelisted Directory Configuration
258
+
259
+ ```json
260
+ "security": {
261
+ "whitelisted_directories": [
262
+ "/home", // System directories
263
+ "/tmp",
264
+ "~", // User's home
265
+ "~/Documents" // Common user directories
266
+ ],
267
+ "auto_approve_directories_in_desktop_mode": false // Set to true for convenience
268
+ }
269
+ ```
270
+
271
+ ### Directory Approval Flow
272
+
273
+ 1. Command is requested in a directory
274
+ 2. System checks:
275
+ - Is the directory in the global whitelist? → **Allow**
276
+ - Has directory been approved in this session? → **Allow**
277
+ - Neither? → **Request approval**
278
+ 3. After approval, directory remains approved for the entire session
279
+
280
+ ### Path Format Support
281
+
282
+ - Absolute paths: `/home/user/documents`
283
+ - Home directory: `~` (expands to user's home)
284
+ - User subdirectories: `~/Downloads`
285
+
286
+ ### Claude Desktop Integration
287
+
288
+ The server maintains a persistent session for Claude Desktop, ensuring directory approvals persist between requests and preventing approval loops.
289
+
290
+ ## Command Customization
291
+
292
+ The system uses command categorization to control access:
293
+
294
+ | Category | Description | Example Commands | Requires Approval |
295
+ |----------|-------------|------------------|-------------------|
296
+ | Read | Safe operations | ls, cat, find | No |
297
+ | Write | Data modification | mkdir, rm, touch | Yes |
298
+ | System | System operations | ps, ping, ifconfig | Yes |
299
+ | Blocked | Dangerous commands | sudo, bash, eval | Always denied |
300
+
301
+ ### Customization Methods
302
+
303
+ ```json
304
+ // In config.json
305
+ {
306
+ "commands": {
307
+ "read": ["ls", "cat", "grep", "awk", "jq"],
308
+ "write": ["mkdir", "touch", "rm"],
309
+ "system": ["ping", "ifconfig", "kubectl"],
310
+ "blocked": ["sudo", "bash", "eval"]
311
+ }
312
+ }
313
+ ```
314
+
315
+ **Environment Variable Method:**
316
+ ```bash
317
+ # Add to existing lists, not replace (comma-separated)
318
+ export CMD_LINE_MCP_COMMANDS_READ="awk,jq"
319
+ export CMD_LINE_MCP_COMMANDS_BLOCKED="npm,pip"
320
+ ```
321
+
322
+ The MCP server merges these additions with existing commands, letting you extend functionality without recreating complete command lists.
323
+
324
+ ### Command Chaining
325
+
326
+ The server supports three command chaining methods:
327
+
328
+ | Method | Symbol | Example | Config Setting |
329
+ |--------|--------|---------|---------------|
330
+ | Pipes | `\|` | `ls \| grep txt` | `allow_command_separators: true` |
331
+ | Sequence | `;` | `mkdir dir; cd dir` | `allow_command_separators: true` |
332
+ | Background | `&` | `find . -name "*.log" &` | `allow_command_separators: true` |
333
+
334
+ All commands in a chain must be from the supported command list. Security checks apply to the entire chain.
335
+
336
+ **Quick Configuration:**
337
+ ```json
338
+ "security": {
339
+ "allow_command_separators": true // Set to false to disable all chaining
340
+ }
341
+ ```
342
+
343
+ To disable specific separators, add them to the `dangerous_patterns` list.
344
+
345
+ ## License
346
+
347
+ MIT
@@ -0,0 +1,319 @@
1
+ # Command-Line MCP Server
2
+
3
+ [![PyPI version](https://badge.fury.io/py/cmd-line-mcp.svg)](https://badge.fury.io/py/cmd-line-mcp)
4
+ [![Python Versions](https://img.shields.io/pypi/pyversions/cmd-line-mcp.svg)](https://pypi.org/project/cmd-line-mcp/)
5
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
6
+
7
+ A secure Model Control Protocol (MCP) server that allows AI assistants to execute terminal commands with controlled directory access and command permissions.
8
+
9
+ ## Overview
10
+
11
+ Command-Line MCP provides a security layer between AI assistants and your terminal. It implements a dual security model:
12
+
13
+ 1. **Command Permissions**: Commands are categorized as read (safe), write (changes data), or system (affects system state), with different approval requirements
14
+ 2. **Directory Permissions**: Commands can only access explicitly whitelisted directories or directories approved during a session
15
+
16
+ AI assistants interact with this server using standardized MCP tools, enabling safe terminal command execution while preventing access to sensitive files or dangerous operations. You can configure the security level from highly restrictive to more permissive based on your needs.
17
+
18
+ ## Key Features
19
+
20
+ | Security | Usability | Integration |
21
+ |----------|-----------|-------------|
22
+ | Directory whitelisting | Command categorization (read/write/system) | Claude Desktop compatibility |
23
+ | Command filtering | Persistent session permissions | Standard MCP protocol |
24
+ | Pattern matching | Command chaining (pipes, etc.) | Auto-approval options |
25
+ | Dangerous command blocking | Intuitive approval workflow | Multiple config methods |
26
+
27
+ ## Supported Commands (out of the box)
28
+
29
+ ### Read Commands
30
+ - `ls`, `pwd`, `cat`, `less`, `head`, `tail`, `grep`, `find`, `which`, `du`, `df`, `file`, `sort`, etc.
31
+
32
+ ### Write Commands
33
+ - `cp`, `mv`, `rm`, `mkdir`, `rmdir`, `touch`, `chmod`, `chown`, etc.
34
+
35
+ ### System Commands
36
+ - `ps`, `top`, `htop`, `who`, `netstat`, `ifconfig`, `ping`, etc.
37
+
38
+ ## Security Architecture
39
+
40
+ The system implements a multi-layered security approach:
41
+
42
+ ```
43
+ ┌───────────────────────────────────────────────────────────────┐
44
+ │ COMMAND-LINE MCP SERVER │
45
+ ├──────────────────┬────────────────────────┬───────────────────┤
46
+ │ COMMAND SECURITY │ DIRECTORY SECURITY │ SESSION SECURITY │
47
+ ├──────────────────┼────────────────────────┼───────────────────┤
48
+ │ ✓ Read commands │ ✓ Directory whitelist │ ✓ Session IDs │
49
+ │ ✓ Write commands │ ✓ Runtime approvals │ ✓ Persistent │
50
+ │ ✓ System commands│ ✓ Path validation │ permissions │
51
+ │ ✓ Blocked list │ ✓ Home dir expansion │ ✓ Auto timeouts │
52
+ │ ✓ Pattern filters│ ✓ Subdirectory check │ ✓ Desktop mode │
53
+ └──────────────────┴────────────────────────┴───────────────────┘
54
+ ```
55
+
56
+ All security features can be configured from restrictive to permissive based on your threat model and convenience requirements.
57
+
58
+ ## Quick Start
59
+
60
+ ```bash
61
+ # Install
62
+ git clone https://github.com/yourusername/cmd-line-mcp.git
63
+ cd cmd-line-mcp
64
+ python -m venv venv
65
+ source venv/bin/activate
66
+ pip install -e .
67
+ cp config.json.example config.json
68
+
69
+ # Run
70
+ cmd-line-mcp # With default config
71
+ cmd-line-mcp --config config.json # With specific config
72
+ ```
73
+
74
+ ### Configuration Options
75
+
76
+ The server supports four configuration methods in order of precedence:
77
+
78
+ 1. **Built-in default configuration** (default_config.json)
79
+ 2. **JSON configuration file** (recommended for customization)
80
+ ```bash
81
+ cmd-line-mcp --config config.json
82
+ ```
83
+ 3. **Environment variables** (for specific overrides)
84
+ ```bash
85
+ export CMD_LINE_MCP_SECURITY_WHITELISTED_DIRECTORIES="~,/tmp"
86
+ ```
87
+ 4. **.env file** (for environment-specific settings)
88
+ ```bash
89
+ cmd-line-mcp --config config.json --env .env
90
+ ```
91
+
92
+ The default configuration is stored in `default_config.json` and is included with the package. You can copy this file to create your own custom configuration.
93
+
94
+ #### Core Configuration Settings
95
+
96
+ ```json
97
+ {
98
+ "security": {
99
+ "whitelisted_directories": ["/home", "/tmp", "~"],
100
+ "auto_approve_directories_in_desktop_mode": false,
101
+ "require_session_id": false,
102
+ "allow_command_separators": true
103
+ },
104
+ "commands": {
105
+ "read": ["ls", "cat", "grep"],
106
+ "write": ["touch", "mkdir", "rm"],
107
+ "system": ["ps", "ping"]
108
+ }
109
+ }
110
+ ```
111
+
112
+ #### Environment Variable Format
113
+
114
+ Environment variables use a predictable naming pattern:
115
+ ```
116
+ CMD_LINE_MCP_<SECTION>_<SETTING>
117
+ ```
118
+
119
+ Examples:
120
+ ```bash
121
+ # Security settings
122
+ export CMD_LINE_MCP_SECURITY_WHITELISTED_DIRECTORIES="/projects,/var/data"
123
+ export CMD_LINE_MCP_SECURITY_AUTO_APPROVE_DIRECTORIES_IN_DESKTOP_MODE=true
124
+
125
+ # Command additions (these merge with defaults)
126
+ export CMD_LINE_MCP_COMMANDS_READ="awk,jq,wc"
127
+ ```
128
+
129
+ ### Claude Desktop Integration
130
+
131
+ #### Setup
132
+
133
+ 1. Install [Claude for Desktop](https://claude.ai/download)
134
+ 2. Configure in `~/Library/Application Support/Claude/claude_desktop_config.json`:
135
+
136
+ ```json
137
+ {
138
+ "mcpServers": {
139
+ "cmd-line": {
140
+ "command": "/path/to/venv/bin/cmd-line-mcp",
141
+ "args": ["--config", "/path/to/config.json"],
142
+ "env": {
143
+ "CMD_LINE_MCP_SECURITY_REQUIRE_SESSION_ID": "false",
144
+ "CMD_LINE_MCP_SECURITY_AUTO_APPROVE_DIRECTORIES_IN_DESKTOP_MODE": "true"
145
+ }
146
+ }
147
+ }
148
+ }
149
+ ```
150
+
151
+ #### Recommended Claude Desktop Settings
152
+
153
+ For best experience, configure:
154
+ - `require_session_id: false` - Essential to prevent approval loops
155
+ - `auto_approve_directories_in_desktop_mode: true` - Optional for convenient access
156
+ - Include common directories in your whitelist
157
+
158
+ After configuration, restart Claude for Desktop.
159
+
160
+ ## AI Assistant Tools
161
+
162
+ The server provides these MCP tools for AI assistants:
163
+
164
+ | Tool | Purpose | Needs Approval |
165
+ |------|---------|----------------|
166
+ | `execute_command` | Run any command type | Yes, for write/system commands |
167
+ | `execute_read_command` | Run read-only commands | Directory approval only |
168
+ | `approve_directory` | Grant access to a directory | N/A - it's an approval tool |
169
+ | `approve_command_type` | Grant permission for command category | N/A - it's an approval tool |
170
+ | `list_directories` | Show authorized directories | No |
171
+ | `list_available_commands` | Show command categories | No |
172
+ | `get_command_help` | Get command usage guidance | No |
173
+ | `get_configuration` | View current settings | No |
174
+
175
+ ### Tool Examples
176
+
177
+ #### Directory Management
178
+
179
+ ```python
180
+ # Check available directories
181
+ dirs = await list_directories(session_id="session123")
182
+ whitelisted = dirs["whitelisted_directories"]
183
+ approved = dirs["session_approved_directories"]
184
+
185
+ # Request permission for a directory
186
+ if "/projects/my-data" not in whitelisted and "/projects/my-data" not in approved:
187
+ result = await approve_directory(
188
+ directory="/projects/my-data",
189
+ session_id="session123"
190
+ )
191
+ ```
192
+
193
+ #### Command Execution
194
+
195
+ ```python
196
+ # Read commands (read permissions enforced)
197
+ result = await execute_read_command("ls -la ~/Documents")
198
+
199
+ # Any command type (may require command type approval)
200
+ result = await execute_command(
201
+ command="mkdir -p ~/Projects/new-folder",
202
+ session_id="session123"
203
+ )
204
+ ```
205
+
206
+ #### Get Configuration
207
+
208
+ ```python
209
+ # Check current settings
210
+ config = await get_configuration()
211
+ whitelist = config["directory_whitelisting"]["whitelisted_directories"]
212
+ ```
213
+
214
+
215
+ ## Directory Security System
216
+
217
+ The server restricts command execution to specific directories, preventing access to sensitive files.
218
+
219
+ ### Directory Security Modes
220
+
221
+ The system supports three security modes:
222
+
223
+ | Mode | Description | Best For | Configuration |
224
+ |------|-------------|----------|--------------|
225
+ | **Strict** | Only whitelisted directories allowed | Maximum security | `auto_approve_directories_in_desktop_mode: false` |
226
+ | **Approval** | Non-whitelisted directories require explicit approval | Interactive use | Default behavior for standard clients |
227
+ | **Auto-approve** | Auto-approves directories for Claude Desktop | Convenience | `auto_approve_directories_in_desktop_mode: true` |
228
+
229
+ ### Whitelisted Directory Configuration
230
+
231
+ ```json
232
+ "security": {
233
+ "whitelisted_directories": [
234
+ "/home", // System directories
235
+ "/tmp",
236
+ "~", // User's home
237
+ "~/Documents" // Common user directories
238
+ ],
239
+ "auto_approve_directories_in_desktop_mode": false // Set to true for convenience
240
+ }
241
+ ```
242
+
243
+ ### Directory Approval Flow
244
+
245
+ 1. Command is requested in a directory
246
+ 2. System checks:
247
+ - Is the directory in the global whitelist? → **Allow**
248
+ - Has directory been approved in this session? → **Allow**
249
+ - Neither? → **Request approval**
250
+ 3. After approval, directory remains approved for the entire session
251
+
252
+ ### Path Format Support
253
+
254
+ - Absolute paths: `/home/user/documents`
255
+ - Home directory: `~` (expands to user's home)
256
+ - User subdirectories: `~/Downloads`
257
+
258
+ ### Claude Desktop Integration
259
+
260
+ The server maintains a persistent session for Claude Desktop, ensuring directory approvals persist between requests and preventing approval loops.
261
+
262
+ ## Command Customization
263
+
264
+ The system uses command categorization to control access:
265
+
266
+ | Category | Description | Example Commands | Requires Approval |
267
+ |----------|-------------|------------------|-------------------|
268
+ | Read | Safe operations | ls, cat, find | No |
269
+ | Write | Data modification | mkdir, rm, touch | Yes |
270
+ | System | System operations | ps, ping, ifconfig | Yes |
271
+ | Blocked | Dangerous commands | sudo, bash, eval | Always denied |
272
+
273
+ ### Customization Methods
274
+
275
+ ```json
276
+ // In config.json
277
+ {
278
+ "commands": {
279
+ "read": ["ls", "cat", "grep", "awk", "jq"],
280
+ "write": ["mkdir", "touch", "rm"],
281
+ "system": ["ping", "ifconfig", "kubectl"],
282
+ "blocked": ["sudo", "bash", "eval"]
283
+ }
284
+ }
285
+ ```
286
+
287
+ **Environment Variable Method:**
288
+ ```bash
289
+ # Add to existing lists, not replace (comma-separated)
290
+ export CMD_LINE_MCP_COMMANDS_READ="awk,jq"
291
+ export CMD_LINE_MCP_COMMANDS_BLOCKED="npm,pip"
292
+ ```
293
+
294
+ The MCP server merges these additions with existing commands, letting you extend functionality without recreating complete command lists.
295
+
296
+ ### Command Chaining
297
+
298
+ The server supports three command chaining methods:
299
+
300
+ | Method | Symbol | Example | Config Setting |
301
+ |--------|--------|---------|---------------|
302
+ | Pipes | `\|` | `ls \| grep txt` | `allow_command_separators: true` |
303
+ | Sequence | `;` | `mkdir dir; cd dir` | `allow_command_separators: true` |
304
+ | Background | `&` | `find . -name "*.log" &` | `allow_command_separators: true` |
305
+
306
+ All commands in a chain must be from the supported command list. Security checks apply to the entire chain.
307
+
308
+ **Quick Configuration:**
309
+ ```json
310
+ "security": {
311
+ "allow_command_separators": true // Set to false to disable all chaining
312
+ }
313
+ ```
314
+
315
+ To disable specific separators, add them to the `dangerous_patterns` list.
316
+
317
+ ## License
318
+
319
+ MIT