<div align="center">

# `envbouncer`

### A tiny local MCP server and CLI that lets AI agents read only allowlisted environment variables, redacts known secrets from text, and logs every access.

![License](https://img.shields.io/badge/license-MIT-blue.svg) ![Language](https://img.shields.io/badge/language-python-green.svg) ![Status](https://img.shields.io/badge/status-active-success.svg) [![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/) [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT) [![MCP](https://img.shields.io/badge/MCP-server-purple)](https://modelcontextprotocol.io)

<img src="demo.gif" alt="Demo" width="700" />

</div>

---

## 🎯 Why?

AI coding agents and MCP servers often need environment variables, but giving them full shell or .env access risks leaking secrets. Existing guardrails mostly block dangerous shell commands or reduce context, but do not broker environment-variable access at runtime. EnvBouncer fills that gap with a declarative allowlist, redaction tooling, and an audit trail.

**Target audience:** Developers using Claude Code, Cursor, Codex, or custom MCP servers who want to grant agents limited access to environment configuration without exposing the entire .env file or shell environment.

## ✨ Features

- ✨ **Declarative TOML allowlist for environment variables**
- ✨ **MCP tools for listing, reading, and redacting allowed variables**
- ✨ **CLI commands for init, check, redact, audit, and stdio MCP serving**
- ✨ **JSONL audit trail for reads, denials, missing variables, and redactions**

## 🚀 Quick Start

```bash
# Install
pip install envbouncer

# Run
envbouncer --help
```

## 📦 Installation

### From Source

```bash
git clone https://github.com/YOUR_USERNAME/envbouncer.git
cd envbouncer
```

```bash
# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest -v
```

## 🎬 Demo

The GIF above was recorded using [Charm VHS](https://github.com/charmbracelet/vhs):

```bash
vhs < demo.tape
```

## 📖 Usage

```bash
# Show help
envbouncer --help

# Common usage examples
envbouncer --example
```

## 🏗️ Architecture

```mermaid
graph LR
    A[Input] --> B[Core Engine]
    B --> C[Output]
    B --> D[Plugins]
    D --> E[Extensions]
```

## 🤝 Contributing

Contributions are welcome! Please:

1. Fork the repo
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 📄 License

MIT © 2026 — See [LICENSE](LICENSE) for details.

---

<div align="center">

**If this project helped you, please ⭐ star it!**

[Made with ❤️ and AI](https://github.com)

</div>