Skip to main content
Glama
Code Firewall MCP
by egoughnour

Code Firewall MCP

PyPI Claude Desktop Tests Release Python 3.10+ License: MIT

Top Language Code Size Last Commit Repository Size

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:#fff
  1. Parse code to Concrete Syntax Tree (CST) using tree-sitter

  2. Normalize by stripping identifiers and literals β†’ structural skeleton

  3. Embed the normalized structure via Ollama

  4. Compare against blacklisted patterns in ChromaDB

  5. 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-mcp

Option 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 sync

Wire 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 serve

  • Pulls 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

firewall_system_check

Check system requirements β€” verify macOS, Apple Silicon, RAM

firewall_setup_ollama

Install via Homebrew β€” managed service, auto-updates

firewall_setup_ollama_direct

Install via direct download β€” no sudo, fully headless

firewall_ollama_status

Check Ollama availability β€” verify embeddings are ready

Firewall Tools

Tool

Purpose

firewall_check

Check if a code file is safe to execute

firewall_check_code

Check code string directly (no file required)

firewall_blacklist

Add a dangerous pattern to the blacklist

firewall_record_delta

Record near-miss variants for classifier sharpening

firewall_list_patterns

List patterns in blacklist or delta collection

firewall_remove_pattern

Remove a pattern from blacklist or deltas

firewall_status

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

FIREWALL_DATA_DIR

/tmp/code-firewall

Data storage directory

OLLAMA_URL

http://localhost:11434

Ollama server URL

EMBEDDING_MODEL

nomic-embed-text

Ollama embedding model

SIMILARITY_THRESHOLD

0.85

Block threshold (0-1)

NEAR_MISS_THRESHOLD

0.70

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:

  1. Initial seeding: Add known dangerous patterns

  2. Audit feedback: When rlm_auto_analyze finds security issues, add patterns

  3. Delta 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:#fff

The normalizer strips:

  • Identifiers: my_var β†’ _ (except security-sensitive ones)

  • String literals: "hello" β†’ "S"

  • Numbers: 42 β†’ N

  • Comments: Removed entirely

Preserved identifiers (for better pattern matching):

  • eval, exec, compile, __import__

  • os, system, popen, subprocess, Popen, shell

  • open, read, write, socket, connect

  • getattr, 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 tools
firewall_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

    A3.7/5.0

    Scored across 11 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Pre-transaction security gate for Pharos AI agents that analyzes contract bytecode and on-chain state to assess risks like upgradeability and honeypot controls.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      A local-first MCP safety layer that blocks dangerous files and redacts secrets before AI agents can access them, ensuring safe vibe coding.
      7 npm
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Protects 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 npm
      2
      ISC