Code Firewall MCP
Integrates with Ollama to generate structural embeddings of code syntax trees, enabling similarity-based detection and blocking of dangerous code patterns.
Click on "Deploy 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., "@Code Firewall MCP check if script.py is safe to execute"
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.
Code Firewall MCP
A structural similarity-based code security filter for MCP (Model Context Protocol). Blocks dangerous code patterns before they reach execution tools by comparing code structure against a blacklist of known-bad patterns.
How It Works
flowchart LR
A[Code<br/>file/string] --> B[Parse & Normalize<br/>tree-sitter]
B --> C[Embed<br/>Ollama]
C --> D{Similarity Check<br/>vs Blacklist}
D -->|β₯ threshold| E[π« BLOCKED]
D -->|< threshold| F[β
ALLOWED]
F --> G[Execution Tools<br/>rlm_exec, etc.]
style E fill:#ff6b6b,color:#fff
style F fill:#51cf66,color:#fff
style D fill:#339af0,color:#fffParse code to Concrete Syntax Tree (CST) using tree-sitter
Normalize by stripping identifiers and literals β structural skeleton
Embed the normalized structure via Ollama
Compare against blacklisted patterns in ChromaDB
Block if similarity exceeds threshold, otherwise allow
Related MCP server: Agent Guards β deterministic security tools for AI agents
Key Insight
Code patterns like os.system("rm -rf /") and os.system("ls") have identical structure. By normalizing away the specific commands/identifiers, we can detect dangerous patterns regardless of the specific arguments used.
Security-sensitive identifiers are preserved during normalization (e.g., eval, exec, os, system, subprocess, Popen, shell) to ensure embeddings remain discriminative for dangerous patterns.
Installation
Quick Start
Option 1: PyPI (Recommended)
uvx code-firewall-mcp
# or
pip install code-firewall-mcpOption 2: Claude Desktop One-Click
Download the .mcpb from Releases and double-click to install.
Option 3: From Source
git clone https://github.com/egoughnour/code-firewall-mcp.git
cd code-firewall-mcp
uv syncWire to Claude Code / Claude Desktop
Add to ~/.claude/.mcp.json (Claude Code) or claude_desktop_config.json (Claude Desktop):
{
"mcpServers": {
"code-firewall": {
"command": "uvx",
"args": ["code-firewall-mcp"],
"env": {
"FIREWALL_DATA_DIR": "~/.code-firewall",
"OLLAMA_URL": "http://localhost:11434"
}
}
}
}Requirements
Python 3.10+ (< 3.14 due to onnxruntime compatibility)
Ollama (for embeddings)
ChromaDB (for vector storage)
tree-sitter (optional, for better parsing)
Setting Up Ollama (Embeddings)
Code Firewall can automatically install and configure Ollama on macOS with Apple Silicon. There are two installation methods:
Method 1: Homebrew Installation
# 1. Check system requirements
firewall_system_check()
# 2. Install via Homebrew
firewall_setup_ollama(install=True, start_service=True, pull_model=True)What this does:
Installs Ollama via Homebrew (
brew install ollama)Starts Ollama as a managed background service
Pulls nomic-embed-text model for embeddings
Method 2: Direct Download (No Sudo)
# 1. Check system
firewall_system_check()
# 2. Install via direct download - no sudo, no Homebrew
firewall_setup_ollama_direct(install=True, start_service=True, pull_model=True)What this does:
Downloads Ollama from https://ollama.com
Extracts to
~/Applications/(no admin needed)Starts Ollama via
ollama servePulls nomic-embed-text model
Manual Setup
# Install Ollama
brew install ollama
# or download from https://ollama.ai
# Start service
brew services start ollama
# or: ollama serve
# Pull embedding model
ollama pull nomic-embed-text
# Verify
firewall_ollama_status()Tools
Setup & Status Tools
Tool | Purpose |
| Check system requirements β verify macOS, Apple Silicon, RAM |
| Install via Homebrew β managed service, auto-updates |
| Install via direct download β no sudo, fully headless |
| Check Ollama availability β verify embeddings are ready |
Firewall Tools
Tool | Purpose |
| Check if a code file is safe to execute |
| Check code string directly (no file required) |
| Add a dangerous pattern to the blacklist |
| Record near-miss variants for classifier sharpening |
| List patterns in blacklist or delta collection |
| Remove a pattern from blacklist or deltas |
| Get firewall status and statistics |
firewall_check
Check if a code file is safe to pass to execution tools.
result = await firewall_check(file_path="/path/to/script.py")
# Returns: {allowed: bool, blocked: bool, similarity: float, ...}firewall_check_code
Check code string directly (no file required).
result = await firewall_check_code(
code="import os; os.system('rm -rf /')",
language="python"
)firewall_blacklist
Add a dangerous pattern to the blacklist.
result = await firewall_blacklist(
code="os.system(arbitrary_command)",
reason="Arbitrary command execution",
severity="critical"
)firewall_record_delta
Record near-miss variants to sharpen the classifier.
result = await firewall_record_delta(
code="subprocess.run(['ls', '-la'])",
similar_to="abc123",
notes="Legitimate use case for file listing"
)firewall_list_patterns
List patterns in the blacklist or delta collection.
firewall_remove_pattern
Remove a pattern from blacklist or deltas.
firewall_status
Get firewall status and statistics.
Configuration
Environment variables:
Variable | Default | Description |
|
| Data storage directory |
|
| Ollama server URL |
|
| Ollama embedding model |
|
| Block threshold (0-1) |
|
| Near-miss recording threshold |
Usage Pattern
Pre-filter for massive-context-mcp
Use code-firewall-mcp as a gatekeeper before passing code to rlm_exec:
# 1. Check code safety
check = await firewall_check_code(user_code)
if check["blocked"]:
print(f"BLOCKED: {check['reason']}")
return
# 2. If allowed, proceed with execution
result = await rlm_exec(code=user_code, context_name="my-context")Integrated with massive-context-mcp
Install massive-context-mcp with firewall integration:
pip install massive-context-mcp[firewall]When enabled, rlm_exec automatically checks code against the firewall before execution.
Building the Blacklist
The blacklist grows through use:
Initial seeding: Add known dangerous patterns
Audit feedback: When
rlm_auto_analyzefinds security issues, add patternsDelta sharpening: Record near-misses to improve classification boundaries
# After security audit finds issues
await firewall_blacklist(
code=dangerous_code,
reason="Command injection via subprocess",
severity="critical"
)Structural Normalization
flowchart TD
subgraph Input
A1["os.system('rm -rf /')"]
A2["os.system('ls -la')"]
A3["os.system(user_cmd)"]
end
subgraph Normalization
B[Strip literals & identifiers<br/>Preserve security keywords]
end
subgraph Output
C["os.system('S')"]
end
A1 --> B
A2 --> B
A3 --> B
B --> C
style C fill:#ff922b,color:#fffThe normalizer strips:
Identifiers:
my_varβ_(except security-sensitive ones)String literals:
"hello"β"S"Numbers:
42βNComments: Removed entirely
Preserved identifiers (for better pattern matching):
eval,exec,compile,__import__os,system,popen,subprocess,Popen,shellopen,read,write,socket,connectgetattr,setattr,__globals__,__builtins__And more security-sensitive names...
Example:
# Original
subprocess.run(["curl", url, "-o", output_file])
# Normalized (preserves 'subprocess' and 'run')
subprocess.run(["S", _, "S", _])Both subprocess.run(["curl", ...]) and subprocess.run(["wget", ...]) normalize to the same structure, so blacklisting one catches both.
License
MIT
Available Tools
11 toolsfirewall_blacklistA
Add a code pattern to the blacklist.
Either file_path or code must be provided.
Args: file_path: Path to code file to blacklist code: Code string to blacklist (alternative to file_path) reason: Why this pattern is dangerous severity: critical, high, medium, low language: Programming language (used if code is provided)
Returns: {"status": "added", "pattern_id": str, "structure_hash": str}
Inputs: file_path, code, reason, severity, +1 more. Returns: object
firewall_checkA
Check if code is safe to pass to execution tools like rlm_exec.
Parses the code, normalizes to structural skeleton, embeds via Ollama, and checks similarity against blacklisted dangerous patterns.
Args: file_path: Path to the code file to check
Returns: { "allowed": bool, # True if safe to proceed "blocked": bool, # True if matched blacklist "similarity": float, # Similarity to closest blacklist match (0-1) "matched_pattern": str, # ID of matched pattern (if blocked) "reason": str, # Why it was blocked (if blocked) "near_miss": bool, # True if close but not blocked "structure_hash": str, # Hash of normalized structure }
Inputs: file_path (required). Returns: object
firewall_check_codeB
Check if code string is safe (without requiring a file).
Args: code: The code to check language: Programming language (default: python)
Returns: Same as firewall_check
Inputs: code (required), language. Returns: object
firewall_list_patternsB
List patterns in the blacklist or delta collection.
Args: collection_name: "blacklist" or "deltas" limit: Maximum number of patterns to return
Returns: {"patterns": [...], "count": int}
Inputs: collection_name, limit. Returns: object
firewall_ollama_statusA
Check Ollama server status and embedding model availability.
Args: force_refresh: Force refresh the cached status
Inputs: force_refresh. Returns: object
firewall_record_deltaA
Record a near-miss variant to help sharpen the classifier.
Use this when code is similar to a blacklisted pattern but represents a legitimate use case, or when a new variant of a dangerous pattern is discovered.
Args: file_path: Path to code file code: Code string (alternative to file_path) similar_to: Pattern ID this is similar to notes: Notes about why this is being recorded language: Programming language
Returns: {"status": "recorded", "delta_id": str}
Inputs: file_path, code, similar_to, notes, +1 more. Returns: object
firewall_remove_patternC
Remove a pattern from the blacklist or delta collection.
Args: pattern_id: The pattern ID to remove collection_name: "blacklist" or "deltas"
Returns: {"status": "removed", "pattern_id": str}
Inputs: pattern_id (required), collection_name. Returns: object
firewall_setup_ollamaB
Install Ollama via Homebrew (macOS).
Args: install: Install Ollama via Homebrew start_service: Start Ollama as a background service pull_model: Pull the embedding model (nomic-embed-text) model: Model to pull (default: nomic-embed-text)
Inputs: install, start_service, pull_model, model. Returns: object
firewall_setup_ollama_directA
Install Ollama via direct download (macOS) - no Homebrew, no sudo.
Args: install: Download and install Ollama to ~/Applications start_service: Start Ollama server in background pull_model: Pull the embedding model (nomic-embed-text) model: Model to pull (default: nomic-embed-text)
Inputs: install, start_service, pull_model, model. Returns: object
firewall_statusB
Get firewall status and statistics.
Returns: { "ollama_available": bool, "chromadb_available": bool, "tree_sitter_available": bool, "blacklist_count": int, "delta_count": int, "similarity_threshold": float, "near_miss_threshold": float, }
Inputs: no named parameters. Returns: object
firewall_system_checkA
Check if system meets requirements for Ollama embeddings.
Verifies: macOS, Apple Silicon (M1/M2/M3/M4), RAM, Homebrew installed. Use before attempting Ollama setup.
Inputs: no named parameters. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
TDQS
Scored across 11 tools
Most tools have distinct purposes, but firewall_check and firewall_check_code are very similarβboth check code safety, differing only in input method (file vs. string). This could cause confusion, though their descriptions clarify the distinction. Other tools like blacklist, remove_pattern, and status are clearly differentiated.
All tool names follow a consistent 'firewall_' prefix with descriptive suffixes in snake_case, such as firewall_blacklist, firewall_check, and firewall_status. This pattern is uniform across all 11 tools, making them predictable and easy to identify.
With 11 tools, the count is well-suited for a code firewall server, covering core operations like blacklisting, checking, setup, and status. Each tool serves a specific role in the domain, avoiding redundancy while providing comprehensive functionality.
The toolset covers key aspects of a code firewall: blacklist management (add, list, remove), safety checks (file and code variants), setup (Ollama installation), and status monitoring. A minor gap is the lack of a tool to update existing patterns, but agents can work around this by removing and re-adding.
Maintenance
Related MCP Connectors
Security firewall for AI agents β scans MCP calls for injection, secrets, and risks.
Detect prompt injection, jailbreaks, and code injection in untrusted text before it reaches an LLM.
The WAF for agents. Pattern-based + heuristic firewall scans prompts, RAG documents, tool argume...
Formally-verified injection/exfiltration detector for AI agents (MCP-02).
Related MCP Servers
- AlicenseNot gradedqualityDmaintenancePre-transaction security gate for Pharos AI agents that analyzes contract bytecode and on-chain state to assess risks like upgradeability and honeypot controls.MIT
- AlicenseNot gradedqualityBmaintenanceInput/output safety gate for AI agents: detect prompt-injection/jailbreak, leaked secrets/PII, and URL/IP reputation. Deterministic, no LLM.1MIT
- AlicenseNot gradedqualityCmaintenanceA local-first MCP safety layer that blocks dangerous files and redacts secrets before AI agents can access them, ensuring safe vibe coding.7 npmApache 2.0
- AlicenseNot gradedqualityBmaintenanceProtects AI agents from prompt injection attacks, jailbreak attempts, and common web vulnerabilities by screening untrusted input through semantic LLM analysis and static pattern matching.71 npm2ISC