This document outlines the security features and best practices for MCP Filesystem Agent.

All file operations are restricted to configured BASE_DIR or BASE_DIRS:

# ✅ ALLOWED
read_file("documents/file.txt")

# ❌ BLOCKED
read_file("../../etc/passwd")
read_file("/etc/password")
read_file("~/../../secret.key")

Implementation: All paths are resolved and validated before operations.

Symlinks are safely resolved and validated:

# If /tmp/link → /tmp/target/data.txt
# ✅ ALLOWED if /tmp/target is in BASE_DIR
# ❌ BLOCKED if /tmp/target is outside BASE_DIR

Implementation: Using Path.resolve() which follows symlinks, then validates target.

Binary files are automatically skipped:

• ✅ Detects .exe, .dll, .pdf, .zip, .png, .jpg, .so, .dylib, etc.
• ✅ Won't attempt to read as text
• ✅ Returns appropriate error message

Configuration: Edit BINARY_EXTENSIONS in server3.py to customize.

Prevents memory exhaustion:

MAX_FILE_SIZE_KB = 2000          # 2MB max file
DEFAULT_CHUNK_SIZE_KB = 50       # 50KB chunks
TOTAL_BATCH_SIZE_KB = 5000       # 5MB max batch

Usage: Automatically enforced, chunked reading available for larger files.

Prevents runaway operations:

MAX_RESULTS = 50                 # Max search results
MAX_LINES_TO_SEARCH = 10000      # Stop after 10K lines

Usage: Returns error if limits exceeded, guides user to narrow search.

All user inputs are validated:

• ✅ Path parameters sanitized
• ✅ Regex patterns validated
• ✅ File content checked before modification
• ✅ Numeric parameters bounds checked

Container runs as unprivileged user:

RUN useradd -m -u 1000 mcp
USER mcp

Benefit: Even if container is compromised, attacker cannot modify system files.

docker run --read-only \
  -v /workspace:rw \
  mcp-filesystem-agent

Benefit: Only /workspace is writable, rest of filesystem is protected.

Never run with --privileged flag.

deploy:
  resources:
    limits:
      cpus: '1'
      memory: 512M

Benefit: Prevents DoS attacks consuming all resources.

• ✅ No network calls made
• ✅ No data sent to external servers
• ✅ No telemetry or reporting
• ✅ Pure file operations only

Exception: When connecting to Claude Desktop or claude.ai, only file operation results are sent (not file contents).

This tool does NOT execute code:

• ✅ No eval() or exec()
• ✅ No shell command execution
• ✅ No Python package installation
• ✅ No binary execution

Safe to use with: Any files, including untrusted code.

All data stays on your machine:

• ✅ No cloud storage
• ✅ No remote logging
• ✅ No analytics
• ✅ No tracking

When connected to Claude Desktop/Web:

• ✅ Only operation results are sent
• ✅ File contents stay local
• ✅ Filenames may be visible to Claude
• ✅ Paths are relative to BASE_DIR

Example:

User: Search for "password" in config files
Claude receives: "Found 3 matches in config.py (line 23, 45, 67)"
Claude does NOT receive: Full file content

python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Benefit: Isolates dependencies from system Python.

# ✅ Good
python server3.py /home/user/projects

# ❌ Avoid
python server3.py /

Benefit: Restricts access to only necessary files. (Env vars MCP_BASE_DIR/MCP_BASE_DIRS work the same way if you prefer those instead.)

docker run -v /source:/workspace:ro \
  mcp-filesystem-agent

Benefit: Prevents accidental or malicious file modifications.

# Only allow from trusted IPs
sudo ufw allow from 192.168.1.0/24 to any port 8000

Benefit: Prevents unauthorized access if exposed.

umask 0077  # Only user can read files
python server3.py

Benefit: Protects file contents from other local users.

pip install --upgrade -r requirements.txt

Benefit: Gets security patches for dependencies.

• ❌ Malicious input in file operations (mitigated by validation)
• ❌ Compromised system Python (use virtual environment)
• ❌ Local privilege escalation (OS responsibility)
• ❌ Physical access to machine (OS responsibility)
• ❌ Social engineering (user responsibility)

• ⚠️ MCP_BASE_DIR should not be / (user responsibility)
• ⚠️ Don't expose over untrusted networks (user responsibility)
• ⚠️ Docker images should be built from trusted source (user responsibility)

Do not report security vulnerabilities as public GitHub issues.

Email: manthandsoni@gmail.com

Include:

• Description of vulnerability
• Steps to reproduce
• Potential impact
• Suggested fix (if any)

Expected Response: Within 48 hours acknowledgment, within 7 days fix or security notice.

1. You report vulnerability privately
2. We investigate and confirm
3. We develop fix
4. We release patch version
5. We publish security advisory
6. You receive credit (if desired)

We follow responsible disclosure practices:

✅ Private reporting encouraged
✅ Reasonable disclosure period
✅ Credit to reporters
✅ Transparency in security issues
✅ Regular security audits

• ✅ OWASP Top 10 secure coding practices
• ✅ CWE-22 prevented (path traversal)
• ✅ CWE-434 mitigated (unrestricted file upload)
• ✅ No hardcoded secrets
• ✅ Input validation on all user inputs

• Formal security audit
• SBOM (Software Bill of Materials)
• CVE tracking
• Automated dependency scanning

Before deployment, verify:

• Dockerfile uses non-root user
• Resource limits are set
• MCP_BASE_DIR is scoped appropriately
• No hardcoded secrets in config
• requirements.txt is up to date
• No debug mode enabled in production
• Proper file permissions (umask)
• Firewall configured (if cloud-deployed)
• Virtual environment used (if local)
• PYTHONUNBUFFERED=1 for better error tracking

Versions with security fixes:

• OWASP: Secure Coding Practices
• CWE-22: Improper Limitation of a Pathname to a Restricted Directory
• Docker Security Best Practices
• Python Security

• 📖 Read README.md
• 🐛 Report issues responsibly
• 🤝 Contribute via CONTRIBUTING.md

Last Updated: July 11, 2026

Policy Version: 1.1

For questions about security, email: manthandsoni@gmail.com