ProcExecMCP
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ProcExecMCPSearch for TODO comments in project"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Archived. Claude Code's built-in Bash tool covers the same use case natively — no MCP server required. The source remains available to clone and adapt under GPLv3+. No further maintenance is planned.
ProcExecMCP
Stateless command execution and process management MCP server for Claude
ProcExecMCP enables Claude (acting in an architectural role) to search code content, execute commands, monitor processes, and terminate processes. The server exposes 4 MCP tools using FastMCP with Python 3.11+, psutil for cross-platform process management, and system ripgrep for file content search.
Features
🔍 search_file_contents: Search for patterns in file contents using ripgrep
⚡ execute_command: Execute commands safely with timeout and output limits
📊 list_processes: List running processes with filtering and sorting
🛑 kill_process: Terminate processes by PID
Related MCP server: Desktop Commander MCP
Security
✅ No shell injection (no
shell=True)✅ Mandatory timeouts on all operations
✅ Resource limits prevent memory exhaustion
✅ Path validation prevents traversal attacks
✅ Sanitized error messages
For comprehensive security documentation, see SECURITY_ARCHITECTURE.md.
Prerequisites
Python 3.11+
uv package manager (installation guide)
ripgrep (rg) binary (installation guide)
Claude Desktop or Claude for Windows
Quick Start
1. Install Dependencies
# Clone repository
git clone https://github.com/Positronikal/ProcExecMCP.git ProcExecMCP
cd ProcExecMCP
# Install with uv
uv sync2. Verify ripgrep
# Check if ripgrep is installed
rg --versionIf not installed:
Windows:
winget install BurntSushi.ripgrep.MSVCmacOS:
brew install ripgrepLinux:
sudo apt install ripgrep
3. Configure Claude Desktop
Edit your Claude Desktop configuration file:
Windows:
%APPDATA%\Claude\claude_desktop_config.jsonmacOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonLinux:
~/.config/Claude/claude_desktop_config.json
Add ProcExecMCP to mcpServers:
{
"mcpServers": {
"procexec": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/ProcExecMCP",
"run",
"procexec"
],
"env": {
"PROCEXEC_TIMEOUT": "30000",
"PROCEXEC_MAX_OUTPUT": "10485760",
"PROCEXEC_ENABLE_KILL": "true",
"PROCEXEC_RIPGREP_PATH": "/path/to/rg"
}
}
}
}Windows Example:
{
"mcpServers": {
"procexec": {
"command": "C:\\Users\\YourName\\.local\\bin\\uv.exe",
"args": [
"--directory",
"D:\\dev\\ProcExecMCP",
"run",
"procexec"
],
"env": {
"PROCEXEC_RIPGREP_PATH": "C:\\Program Files\\ripgrep\\rg.exe"
}
}
}
}4. Restart Claude Desktop
Close and reopen Claude Desktop to load the new MCP server.
5. Verify Installation
In Claude, try:
What MCP tools do you have available?You should see all 4 ProcExecMCP tools listed.
Configuration
Environment Variables
PROCEXEC_TIMEOUT: Command timeout in milliseconds (default: 30000, range: 1000-300000)
PROCEXEC_MAX_OUTPUT: Maximum output size in bytes (default: 10485760 = 10MB)
PROCEXEC_BLOCKED_PATHS: Comma-separated list of paths to block access
PROCEXEC_ENABLE_KILL: Enable process termination tool (default: "true")
PROCEXEC_RIPGREP_PATH: Full path to ripgrep binary (use if not in PATH)
Security Considerations
Blocked Paths: Configure
PROCEXEC_BLOCKED_PATHSto protect sensitive directoriesProcess Termination: Disable with
PROCEXEC_ENABLE_KILL="false"if not neededTimeouts: Set appropriate limits to prevent runaway commands
Privileges: Avoid running Claude Desktop with elevated privileges unless necessary
Usage Examples
Search for Code Patterns
Search for all TODO comments in my Python project at /path/to/projectExecute Analysis Tools
Run 'pylint src/' in my project directory and show the resultsMonitor Processes
List all Python processes sorted by memory usageTerminate Stuck Processes
Terminate process 1234 gracefullyDevelopment
For development setup, running tests, modifying the server, and building documentation, see USING.md.
Documentation
Quick Start: See above
Detailed Usage: USING.md
Security Architecture: SECURITY_ARCHITECTURE.md
API Documentation:
docs/directory (Doxygen generated)Troubleshooting: BUGS.md
Contributing: CONTRIBUTING.md
Troubleshooting
ripgrep not found
Ensure ripgrep is installed and in PATH, or set PROCEXEC_RIPGREP_PATH environment variable.
Timeout errors
Increase timeout via PROCEXEC_TIMEOUT environment variable (milliseconds).
Permission denied
Check file/directory permissions or configure PROCEXEC_BLOCKED_PATHS.
For more troubleshooting guidance, see BUGS.md.
License
This project is licensed under the GNU General Public License version 3 or any later version (GPLv3+). See COPYING.md for the full license text.
Contributing
Contributions are welcome! Please read CONTRIBUTING.md for guidelines.
Support
Issues: GitHub Issues
Security: See SECURITY.md for responsible disclosure
Documentation: See
docs/for API reference
Available Tools
4 toolsexecute_commandA
Execute a command safely with timeout and output limits.
This tool executes commands without shell injection vulnerabilities. Commands are parsed into argument lists and executed directly via subprocess without shell=True.
Args: command: Command to execute (e.g., "python --version", "npm test") working_directory: Working directory for execution (default: current) timeout_ms: Timeout in milliseconds (default: 30000, max: 300000) capture_output: Whether to capture stdout/stderr (default: True) ctx: MCP context for logging (optional)
Returns: ExecuteCommandOutput with stdout, stderr, exit code, and timing
Raises: ValueError: If input validation fails SanitizedError: If command execution fails
Security: - No shell=True (prevents shell injection) - Command parsed with shlex.split (safe parsing) - Mandatory timeout enforcement - Output size limits (prevents memory exhaustion) - Path validation for working directory - Sanitized error messages (no information leakage)
Examples: >>> result = await execute_command("python --version") >>> print(result.stdout) # "Python 3.11.5" >>> print(result.exit_code) # 0
>>> result = await execute_command(
... "npm test",
... working_directory="./myproject",
... timeout_ms=60000
... )
| Name | Required | Description | Default |
|---|---|---|---|
| command | Yes | ||
| timeout_ms | No | ||
| capture_output | No | ||
| working_directory | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| stderr | Yes | Standard error from the command |
| stdout | Yes | Standard output from the command |
| exit_code | Yes | Exit code returned by the command (0 typically means success) |
| timed_out | Yes | Whether the command was terminated due to timeout |
| output_truncated | Yes | Whether output was truncated due to size limit |
| execution_time_ms | Yes | Time taken to execute command in milliseconds |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Comprehensively covers safety features (no shell injection, timeout, output limits, path validation, sanitized errors), return type, and exceptions. No annotations provided, so description fully shoulders the burden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with front-loaded purpose, then detailed sections (Args, Returns, Raises, Security, Examples). Every section adds value without redundancy; appropriate length for a safety-critical tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given four parameters, one required, and existence of output schema, the description covers inputs, behavior, return type, and exceptions completely. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although input schema has 0% description coverage, the description's Args section defines each parameter with examples, defaults, and constraints (e.g., timeout max, capture_output default), fully compensating.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Execute a command safely with timeout and output limits'. Specific verb+resource, distinguishes from siblings by focusing on command execution rather than file or process management.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context and examples for typical use cases, but does not explicitly contrast with sibling tools (search_file_contents, list_processes, kill_process) for when to avoid this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
kill_processA
Terminate a process by PID with graceful or forced termination.
This tool allows terminating stuck or hung processes to clean up system resources. It supports both graceful termination (SIGTERM/WM_CLOSE) with a timeout, and forced termination (SIGKILL/TerminateProcess) for unresponsive processes.
Args: pid: Process ID to terminate (must be >= 1) force: If True, forcefully kill the process. If False, attempt graceful termination with timeout. Default: False timeout_seconds: Timeout in seconds to wait for graceful termination. Ignored if force=True. Range: 0.1-30.0s. Default: 5.0s ctx: MCP context for logging (optional)
Returns: KillProcessOutput with success status, PID, message, timing, and whether forced termination was used
Raises: SanitizedError: If process termination fails or is not enabled
Security: - Requires PROCEXEC_ENABLE_KILL=true environment variable to function - Handles permission errors gracefully (no crashes) - Cannot terminate system-critical processes (OS protection) - Error messages are sanitized (no sensitive info)
Examples: >>> # Graceful termination >>> result = await kill_process(pid=1234, force=False, timeout_seconds=5.0) >>> print(result.success, result.message) True 'Process terminated gracefully'
>>> # Forced termination
>>> result = await kill_process(pid=5678, force=True)
>>> print(result.success, result.forced)
True True
| Name | Required | Description | Default |
|---|---|---|---|
| pid | Yes | ||
| force | No | ||
| timeout_seconds | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| pid | Yes | Process ID that was targeted for termination |
| forced | Yes | Whether forced termination (SIGKILL) was used |
| message | Yes | Human-readable status message describing the outcome |
| success | Yes | Whether the process was successfully terminated |
| termination_time_ms | Yes | Time taken to terminate the process in milliseconds |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavior: graceful and forced termination, timeout handling, security requirements (PROCEXEC_ENABLE_KILL), permission errors, system-critical protection, and sanitized errors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections (Args, Returns, etc.) and examples. Slightly verbose but every sentence adds value; minor trimming could improve conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all aspects: parameters, return values, error handling, security, and examples. Output schema exists but description already explains return fields; fully adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage; the description adds full semantics for all parameters: pid (>=1), force (default false), timeout_seconds (range 0.1-30.0, default 5.0, ignored if force).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Terminate a process by PID' with specific methods (graceful/forced), and is distinct from sibling tools like execute_command or list_processes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides context for when to use (stuck/hung processes) and differentiates graceful vs forced termination, but lacks explicit exclusion or comparison with sibling tools, which is acceptable given their distinct purposes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_processesA
List running processes with optional filtering and sorting.
This tool retrieves information about running processes on the system, including PID, name, CPU usage, memory usage, command line, and status. Results can be filtered by name, sorted by various criteria, and limited to a maximum number of results.
Args: name_filter: Filter processes by name (case-insensitive substring match). If None, return all processes. sort_by: Sort processes by: cpu (descending), memory (descending), pid (ascending), or name (ascending). Default: cpu. limit: Maximum number of processes to return. Default: 100, max: 1000. ctx: MCP context for logging (optional)
Returns: ListProcessesOutput with process list, total count, truncation flag, and retrieval time
Raises: SanitizedError: If process iteration fails
Security: - Handles permission errors gracefully (skips inaccessible processes) - No sensitive system information leaked in errors - Command lines are included but may be empty if access denied - Zombie and terminated processes handled without errors
Performance: - Uses psutil.process_iter() for efficient iteration - oneshot() context for batch info retrieval per process - Target: <2s for process list retrieval
Examples: >>> result = await list_processes() >>> print(result.total_count, "processes found") 245 processes found
>>> result = await list_processes(
... name_filter="python",
... sort_by=ProcessSortBy.MEMORY,
... limit=50
... )
>>> for proc in result.processes:
... print(f"{proc.name}: {proc.memory_mb}MB")
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| sort_by | No | cpu | |
| name_filter | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| processes | Yes | List of process information |
| truncated | Yes | Whether results were truncated due to limit |
| total_count | Yes | Total number of processes found (before limit applied) |
| retrieval_time_ms | Yes | Time taken to retrieve process information in milliseconds |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and excels: it discloses security handling (permission errors, no sensitive leaks), performance targets (<2s), error types (SanitizedError), and edge cases (zombie processes). It also describes the output structure, making agent behavior predictable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (Args, Returns, Raises, Security, Performance, Examples) and front-loads the key action. It is slightly lengthy but each section earns its place, providing necessary detail without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite an output schema existing (context signal), the description still clarifies the return fields (ListProcessesOutput) and covers all aspects: purpose, parameters, errors, security, performance. Nothing obvious is missing for a process listing tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, this document compensates fully. Each parameter is explained: name_filter (case-insensitive substring), sort_by (enum with direction), limit (max 1000, default 100). The description adds value beyond the schema's bare types and titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'List running processes with optional filtering and sorting,' which clearly identifies the verb (list) and resource (running processes). It distinguishes effectively from sibling tools like execute_command, search_file_contents, and kill_process, which have different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
While the description does not explicitly contrast with siblings, it provides clear context for when to use the tool, including detailed parameter usage and security/performance considerations. Siblings are sufficiently different that explicit exclusions are less critical.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_file_contentsA
Search for patterns in file contents across a directory or file.
This tool uses ripgrep to efficiently search for regex patterns in files. It returns matches with line numbers and surrounding context lines.
Args: pattern: Regular expression pattern to search for path: File or directory path to search in case_sensitive: Whether search should be case-sensitive (default: True) file_types: File type filters (e.g., ['py', 'js']). None = all files exclude_patterns: Glob patterns to exclude (e.g., ['node_modules']) max_results: Maximum number of results to return (1-10000) context_lines: Lines of context before/after match (0-10) ctx: MCP context for logging (optional)
Returns: SearchFileContentsOutput with matches and metadata
Raises: ValueError: If input validation fails SanitizedError: If search execution fails
Examples: >>> result = search_file_contents("TODO", "./src", case_sensitive=False) >>> print(f"Found {len(result.matches)} TODO comments")
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| pattern | Yes | ||
| file_types | No | ||
| max_results | No | ||
| context_lines | No | ||
| case_sensitive | No | ||
| exclude_patterns | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| matches | Yes | List of search matches found |
| truncated | Yes | Whether results were truncated due to max_results limit |
| total_matches | Yes | Total number of matches found (may exceed returned matches if limited) |
| files_searched | Yes | Number of files searched |
| search_time_ms | Yes | Time taken to complete search in milliseconds |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the use of ripgrep, return type with matches and metadata, and error cases. However, it does not mention potential performance issues with large directories or default behavior like respecting .gitignore, which would be helpful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a concise one-line summary, a brief paragraph about the tool, a detailed argument list, return/error info, and an example. It is front-loaded with the core purpose and each sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite 7 parameters and only 2 required, the description covers all parameters, return type, and errors. The presence of an output schema (mentioned) reduces the need to detail return fields. An example is provided. For a tool of this complexity, it is very complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, meaning no parameter descriptions in JSON. The description compensates fully by listing all 7 parameters with clear explanations of their purpose and defaults. Examples further clarify usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a clear verb ('Search') and resource ('file contents'), specifying the action of pattern searching across a directory or file. It distinguishes from sibling tools (execute_command, list_processes, kill_process) which serve entirely different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains how to use the tool (regex search, file type filters, context lines) but does not explicitly state when NOT to use it or mention alternatives among siblings. However, siblings are unrelated, so the lack of explicit exclusions is acceptable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
4 tool updates
v0.1.0- First observed
execute_command - First observed
kill_process - First observed
list_processes - First observed
search_file_contents
TDQS
Each tool has a distinct purpose: executing commands, searching file contents, listing processes, and killing processes. There is no functional overlap, and descriptions clearly differentiate them.
All tool names follow a consistent verb_noun pattern in snake_case: execute_command, search_file_contents, list_processes, kill_process. The naming is predictable and uniform.
With only 4 tools, the set is well-scoped for its purpose of process and command management plus file content searching. Each tool earns its place with comprehensive parameters and security considerations.
The tool surface covers the core operations for its domain: command execution, file content search, process enumeration, and process termination. There are no obvious gaps for the intended functionality.
Maintenance
Related MCP Connectors
Personal assistant MCP server with search, execute, packages, jobs, secrets, and integrations.
Augments MCP Server - A comprehensive framework documentation provider for Claude Code
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Related MCP Servers
- AlicenseBqualityDmaintenanceA secure MCP server for executing whitelisted shell commands with resource and timeout controls, designed for integration with Claude and other MCP-compatible LLMs.203897MIT
- AlicenseAqualityDmaintenanceA server that lets Claude desktop app execute terminal commands on your computer and edit files through Model Context Protocol, featuring command execution, process management, and advanced file operations.1938,9236MIT
- FlicenseNot gradedqualityDmaintenanceA server implementation for the Model Context Protocol (MCP) that allows Claude AI to execute commands through a command-line interface, enabling direct system interactions from within Claude.-
- FlicenseBqualityDmaintenanceMulti-mode MCP server supporting both Claude Desktop (STDIO) and OpenAI (HTTP/SSE) integrations with file operations including read, write, delete, and search capabilities.3-
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/hoyt-harness/ProcExecMCP'
If you have feedback or need assistance with the MCP directory API, please join our Discord server