# MCP Firewall

A policy and audit layer for Model Context Protocol (MCP).

MCP Firewall sits transparently between any MCP client (Claude Desktop, Cursor, VS Code, etc.) and an upstream MCP server, allowing you to inspect, allow, block, or audit requests before they reach the server.

No changes are required to your client or your MCP server.

---

## Status

MCP Firewall is an early open-source project.

The core stdio proxy, policy engine, audit logging, and enforcement pipeline are implemented and tested against the official MCP reference servers.

Feedback, bug reports, and contributions are welcome.

---

## Why?

MCP servers can expose powerful capabilities such as:

- Reading files
- Writing files
- Executing shell commands
- Accessing databases
- Calling internal APIs

Once an AI agent has access to those tools, there is normally no policy layer deciding what should or shouldn't be allowed.

MCP Firewall adds that missing layer.

Instead of talking directly to an MCP server, the client talks to MCP Firewall. Every request is evaluated against your policy, recorded in the audit log, and either forwarded or blocked before reaching the upstream server.

---

## How it works

Without MCP Firewall

```text
Claude Desktop
      │
      ▼
Filesystem MCP Server
      │
      ▼
delete_file()
      │
      ▼
File deleted
```

With MCP Firewall

```text
Claude Desktop
      │
      ▼
MCP Firewall
      │
      ├── Policy Evaluation
      ├── Audit Logging
      └── Read-only Checks
      │
      ▼
BLOCK delete_file()
      │
      ▼
JSON-RPC Error returned to the client

(The upstream server never receives the request.)
```

---

# Features

Current release includes:

- Transparent stdio proxy
- Tool allow lists
- Tool deny lists
- Parameter-aware policy rules (`match_params`)
- Read-only mode
- Structured JSON audit logging
- Audit-only mode
- JSON-RPC compliant error responses
- Single Go binary
- No changes required to existing MCP clients or servers

---

# Installation

## Option 1: Download Pre-built Binary (Recommended)

Download the latest ready-to-run binary for Windows from the **[GitHub Releases](https://github.com/venu1222g/mcp-firewall/releases)** page.

1. Download `mcp-firewall.exe`.
2. Place it in your project directory or system PATH.
3. Run `mcp-firewall.exe init` to generate a default configuration file.

---

## Option 2: Build from Source (Requires Go 1.22+)

### Requirements

- Go 1.22+
- Node.js (only if using official Node-based MCP reference servers)

Clone the repository:

```bash
git clone https://github.com/venu1222g/mcp-firewall.git
cd mcp-firewall

Build:

```bash
make build
```

or

```bash
go build -o mcp-firewall ./cmd/firewall
```

---

# Quick Start

Generate a configuration:

```bash
./mcp-firewall init
```

Start the firewall:

```bash
./mcp-firewall run --config mcp-firewall.yaml
```

Then point your MCP client at the firewall instead of the upstream server.

Example (Claude Desktop):

```json
{
  "mcpServers": {
    "filesystem": {
      "command": "/path/to/mcp-firewall",
      "args": [
        "run",
        "--config",
        "/path/to/mcp-firewall.yaml"
      ]
    }
  }
}
```

Restart your MCP client.

Every request now passes through MCP Firewall before reaching the upstream server.

---

# Configuration Examples

## Block a tool

```yaml
policy:
  default_action: allow
  tools:
    deny:
      - delete_file
```

---

## Allow only selected tools

```yaml
policy:
  default_action: block
  tools:
    allow:
      - read_file
      - list_directory
```

---

## Protect a specific file

```yaml
policy:
  default_action: allow
  rules:
    - id: protect-secrets
      method: tools/call
      action: block
      match_params:
        path: /etc/secrets.env
```

---

## Audit a policy before enforcing it

```yaml
server:
  mode: audit-only
```

Requests continue to reach the upstream server, but every policy decision is evaluated and recorded.

When you're satisfied with the policy, switch to:

```yaml
server:
  mode: enforce
```

---

## Enable read-only mode

```yaml
read_only:
  enabled: true
```

Read-only mode blocks supported write/delete operations while continuing to allow read operations.

---

# CLI

Generate a default configuration:

```bash
mcp-firewall init
```

Run the proxy:

```bash
mcp-firewall run --config mcp-firewall.yaml
```

Validate configuration and environment:

```bash
mcp-firewall doctor
```

Show version information:

```bash
mcp-firewall version
```

---

# Tested Against

This release has been verified against:

- Official `@modelcontextprotocol/server-filesystem`
- Official `@modelcontextprotocol/server-everything`
- JSON-RPC 2.0 stdio transport
- Windows

---

# Known Limitations

MCP Firewall is currently at **v0.1.x**.

The following limitations are known:

- Tool allow/deny policies perform exact tool-name matching.
- `match_params` currently matches scalar values only. Array-valued parameters are not matched.
- Read-only mode protects a built-in list of supported write/delete tools using exact tool names.
- Dynamic MCP capability annotations (`readOnlyHint` / `destructiveHint`) are not yet used.
- `action: redact` is reserved for a future release and currently behaves as a block.

---

# Roadmap

Planned improvements include:

- Regex and glob matching
- Dynamic capability discovery
- Parameter redaction
- HTTP/SSE transport support
- Web dashboard

---

# Contributing

Contributions are welcome.

```bash
make fmt
make test
```

Please open an issue before making large architectural changes or adding new features.

---

# License

Apache License 2.0.