ABSD DevOps MCP Server
Local-first Model Context Protocol (MCP) server providing secure filesystem and terminal operations for AI assistants.
Features
- 22 Powerful Tools: 9 filesystem + 4 streaming search + 7 terminal + 2 meta operations
- Filesystem Operations: Read (files/URLs/images), write, list, create, move/rename, search (ripgrep), edit (surgical), multi-read
- Streaming Search: Background ripgrep with pagination, session management, and early termination
- Terminal Sessions: Interactive REPLs (Python, Node.js) with ANSI-aware prompt detection
- Process Management: List system processes, kill with confirmation tokens
- Image Support: MCP native ImageContent for PNG, JPEG, GIF, WebP, BMP (SVG as text for security)
- URL Fetching: HTTP/HTTPS with configurable timeout and denylist protection
- MCP Primitives: Resources (server state) + Prompts (workflow templates)
- Security-First: Path traversal protection, command filtering, input sanitization, unrestricted mode with warnings
- Type-Safe: Built with TypeScript strict mode and Zod schema validation
- Local-Only: Runs entirely on your machine via stdio transport
⚠️ v0.3.3 Compatibility Update: Node.js requirement lowered to >= 20.0.0 and native modules are now built against Node 20 so Claude Desktop can load the server without module-version errors. If you installed before v0.3.3, reinstall globally and restart Claude Desktop.
⚠️ v0.3.2 Security Update: Default blocked commands expanded from 6 to 31 (destructive disk operations, system/network modifications, package manager removals, data destruction). Existing installations: Review your ~/ABSD_MCP/config.json and merge new blocked commands from config.example.json to benefit from enhanced security.
Installation
Quick Start (Recommended)
# 1. Install globally
npm install -g @anthonybir/devops-mcp
# 2. Run setup (interactive)
absd-mcp-setup
The setup command will:
- ✅ Add MCP server to Claude Desktop config
- ✅ Create default config at
~/ABSD_MCP/config.json - ✅ Backup your existing Claude config with timestamp
⚠️ Security Warning: Default config allows access to your entire home directory.
Review and restrict allowedDirectories immediately after setup.
Next steps:
- Review config:
~/ABSD_MCP/config.json(macOS) or%USERPROFILE%\ABSD_MCP\config.json(Windows) - Restrict
allowedDirectoriesto only needed paths - Restart Claude Desktop
Uninstall
# Remove from Claude Desktop config
absd-mcp-unregister
# Uninstall package
npm uninstall -g @anthonybir/devops-mcp
Manual Setup
If you prefer manual configuration, see Claude Desktop Setup below.
Using npx (No Installation)
npx @anthonybir/devops-mcp@latest
Requires manual Claude Desktop configuration (see below).
Codex CLI Setup (TOML)
If you run the Codex CLI, install the package globally first and then add an MCP entry to your codex.toml:
[[mcp]]
name = "absd-devops"
command = "absd-mcp"
args = []
working_directory = "/Users/yourusername"
env = { ABSD_MCP_CONFIG = "/Users/yourusername/ABSD_MCP/config.json" }
After saving the file run codex mcp reload (or restart Codex) so the new server is picked up. Update the paths to match your environment.
From Source
git clone https://github.com/anthonybir/ABSD_MCP.git
cd ABSD_MCP
pnpm install
pnpm build
Configuration
Create a config.json file (or copy from config.example.json):
{
"allowedDirectories": [
"/Users/yourusername/Projects",
"/Users/yourusername/Documents"
],
"blockedCommands": [
"rm -rf /",
"dd if=/dev/zero",
"mkfs",
"shutdown",
"reboot"
// ... see config.example.json for full list of 31 default blocked commands
],
"fileReadLineLimit": 2000,
"fileWriteLineLimit": 75,
"sessionTimeout": 1800000,
"logLevel": "info",
"urlDenylist": ["localhost", "127.0.0.1", "0.0.0.0", "::1"],
"urlTimeout": 10000
}
Configuration Options
- allowedDirectories: Array of absolute paths where file operations are permitted (empty array = unrestricted access)
- blockedCommands: Array of dangerous commands to reject (default: [])
- fileReadLineLimit: Maximum lines to read per file operation (default: 1000)
- fileWriteLineLimit: Maximum lines to write per operation (default: 50)
- sessionTimeout: Process session timeout in milliseconds (default: 1800000 = 30 minutes)
- logLevel: Logging level (
debug|info|warn|error) (default:info) - urlDenylist: Array of hostnames to block for URL fetching (default:
["localhost", "127.0.0.1", "0.0.0.0", "::1"]) - urlTimeout: URL fetch timeout in milliseconds (default: 10000 = 10 seconds)
Enable Full Filesystem Access (Advanced)
Set allowedDirectories to an empty array ([]) if you want ABSD to access every path on your machine. You must keep blockedCommands populated—the server will refuse to start if both lists are empty.
{
"allowedDirectories": [],
"blockedCommands": [
"rm -rf /",
"dd if=/dev/zero",
"mkfs",
"shutdown",
"reboot",
"init 0"
// ...and the rest from config.example.json
]
}
Only use unrestricted mode on trusted local machines and keep the expanded blocked-commands list (31 entries) to avoid accidental destructive commands.
Path Formatting
Windows users: Use forward slashes in JSON to avoid escaping issues:
- ✅
"C:/Users/yourusername/Projects" - ✅
"C:\\\\Users\\\\yourusername\\\\Projects"(double-escaped backslashes) - ❌
"C:\Users\yourusername\Projects"(breaks JSON)
macOS/Linux users: Standard absolute paths:
- ✅
"/Users/yourusername/Projects" - ✅
"/home/username/projects"
Claude Desktop Setup
Config File Locations:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
Option 1: Using Installed Package (Offline-Compatible)
If you installed globally, reference the bin entry:
{
"mcpServers": {
"absd-devops": {
"command": "absd-mcp",
"args": [],
"env": {
"ABSD_MCP_CONFIG": "/path/to/your/config.json"
}
}
}
}
Option 2: Using npx (Online-Only)
If using npx or want latest version:
{
"mcpServers": {
"absd-devops": {
"command": "npx",
"args": ["-y", "@anthonybir/devops-mcp@latest"],
"env": {
"ABSD_MCP_CONFIG": "/path/to/your/config.json"
}
}
}
}
ABSD_MCP_CONFIG paths:
- macOS: Use full path like
/Users/yourusername/ABSD_MCP/config.json - Windows: Use forward slashes like
C:/Users/yourusername/ABSD_MCP/config.json
Restart Claude Desktop to activate the server.
Available Tools
Filesystem Tools (9)
- read_file: Read files or URLs with image support (PNG, JPEG, GIF, WebP, BMP), optional chunking, and offset support (SVG treated as text for security)
- read_multiple_files: Read multiple files simultaneously with size caps (1MB/file, 5MB total)
- write_file: Create or overwrite files with append mode option
- list_directory: List directory contents recursively with depth control
- create_directory: Create directories with recursive parent creation
- move_file: Move or rename files and directories (both paths validated for security)
- get_file_info: Get detailed metadata (size, permissions, timestamps, line count)
- search_files: Search for patterns using ripgrep (regex, literal, file filtering)
- edit_block: Surgical text replacement with uniqueness validation
Streaming Search Tools (4)
- start_search: Initiate background ripgrep search with files or content mode
contextLines: Lines of context around matches (default: 3)- Tip: Set
contextLines: 0for terse output with no surrounding context
- get_more_search_results: Retrieve paginated results with offset-based navigation
- stop_search: Terminate running search sessions early
- list_searches: View all active search sessions with status and result counts
Terminal Tools (7)
- start_process: Launch interactive terminal sessions (Python, Node.js, bash)
- interact_with_process: Send commands with ANSI-aware REPL prompt detection (strip-ansi)
- read_process_output: Retrieve buffered output from background processes
- list_sessions: View all active MCP terminal sessions with status
- terminate_process: Stop MCP sessions by PID
- list_processes: List all system processes (cross-platform: Windows/macOS/Linux)
- kill_process: Kill system processes with confirmation token validation
Meta Tools (2)
- get_config: Get current server configuration (read-only) with security status and metadata
- get_usage_stats: Get server usage statistics including uptime, tool call counts (successful calls only), and active sessions/searches. Stats reset when server restarts.
MCP Primitives
Resources
Expose server state and configuration:
- config://absd-mcp/server: Current server configuration (allowed directories, limits)
- state://absd-mcp/sessions: Active terminal sessions with status
Prompts
Pre-configured templates for common workflows:
- analyze_codebase: Analyze project structure and tech stack
- setup_python_env: Interactive Python development environment
- search_and_replace: Pattern search with guided replacement
Security
This MCP server implements multiple security layers:
- Path Validation: All file operations validate against allowed directories
- Symlink Resolution: Prevents symlink-based path traversal attacks
- Command Filtering: Blocks dangerous terminal commands
- Input Sanitization: Removes null bytes and control characters
- Zod Validation: All tool inputs validated against strict schemas
Development
Running Tests
pnpm test # Run all tests
pnpm test:security # Run security tests only
Building
pnpm build # Build for production
pnpm dev # Development mode with watch
Testing with MCP Inspector
npx @modelcontextprotocol/inspector pnpm dev
Troubleshooting
Server Not Appearing in Claude
- Check that config.json path is correct in claude_desktop_config.json
- Restart Claude Desktop completely
- Check Claude's MCP logs for errors
Permission Errors
Ensure all paths in allowedDirectories exist and are accessible by your user account.
Command Blocked
If a legitimate command is being blocked, review the blockedCommands array in your config.
Contributing
Contributions are welcome! Please:
- Fork the repository
- Create a feature branch
- Add tests for new functionality
- Ensure all tests pass (
pnpm test) - Submit a pull request
License
MIT License - see LICENSE file for details.
Author
Anthony Bir anthonybir@aena.edu.py