Ears everywhere in your stack.
Fennec is an AI-native developer observability MCP (Model Context Protocol) server that gives AI agents full-stack visibility into your development environment — browser, terminal, and processes — all in one unified interface.
When a developer asks an AI agent "why is my login broken?", the agent is essentially blind:
What agent sees: What developer sees:
───────────────── ──────────────────────────────────
"I can't access Browser Console:
your terminal" ✗ TypeError: jwt.sign is undefined
"Please paste the Terminal:
error message" ✗ Error: JWT_SECRET not set in env
"I don't have Network Tab:
browser access" ✗ POST /api/login -> 500
The developer ends up being a copy-paste bridge between their tools and the AI. Fennec eliminates this bottleneck.
With Fennec, your AI agent can:
- 🔍 Observe browser console logs, network requests, and performance metrics in real-time
- 🖥️ Watch terminal output and server logs without changing your workflow
- ⚙️ Control browser sessions — navigate, click, type, screenshot, and more
- 🔗 Correlate events across layers to identify root causes automatically
- 🔐 Persist authentication sessions across conversations
- 🧩 Diagnose full-stack issues with a single command
Fennec supports three modes, which can be combined:
Developer runs their server normally, Fennec listens passively.
# Pipe server output to Fennec
npm run dev 2>&1 | fennec pipe --name "dev-server"
# Or attach to an existing process
fennec attach-pid 12345
fennec attach-port 3000AI spawns and manages processes directly.
# AI can:
# 1. Spawn npm run dev
# 2. Wait for server ready
# 3. Open browser
# 4. Execute tasks
# 5. Report resultsDeveloper spawns server, AI controls browser + observes logs.
# Terminal A: Run server
npm run dev 2>&1 | fennec pipe --name "dev-server"
# Terminal B: AI agent has full visibility- Navigation & interaction (click, type, scroll, drag-drop)
- DOM queries, accessibility tree, element inspection
- Multi-tab and multi-context support
- Screenshots (full page, element, viewport)
- Console: Real-time log collection, filtering, error tracking
- Network: Full request/response monitoring, interception, mocking
- Performance: FCP, LCP, TBT, CLS metrics, memory profiling
- Storage: localStorage, sessionStorage, cookies, IndexedDB
- Auto-detect and fill login forms
- Save/load authenticated sessions across conversations
- Multi-session parallel testing (e.g., admin + regular user)
- Spawn, monitor, and interact with processes
- Attach to running processes by PID or port
- Watch log files and pipe streams
- Auto-detect log levels (error, warn, info, debug)
Fennec's signature feature — correlate browser errors with server logs and process state to identify root causes automatically.
{
"correlation": {
"rootCause": "JWT_SECRET environment variable missing on server",
"confidence": 0.94,
"fix": "Add JWT_SECRET to your .env file",
"timeline": [
{ "t": "+0ms", "layer": "browser", "event": "POST /api/auth/login initiated" },
{ "t": "+12ms", "layer": "server", "event": "Request received at auth router" },
{ "t": "+13ms", "layer": "server", "event": "ERROR: JWT_SECRET not set" },
{ "t": "+15ms", "layer": "browser", "event": "Network failure received" },
{ "t": "+16ms", "layer": "browser", "event": "TypeError thrown in auth.js:67" }
]
}
}- Getting Started Guide
- Full Tool Reference — 90+ MCP tools across 12 groups
- Guides
- Auth Flows — login forms, session persistence, multi-user
- Debugging SPAs — React, Vue, Next.js debugging
- Full-Stack Debugging — correlate browser ↔ server errors
- Multi-Session Testing — parallel isolated sessions
- Security Model — sandbox, allowlists, best practices
- Configuration Reference — all config options + env vars
- Usage Examples — step-by-step JSON-RPC walkthroughs
| Requirement | Version |
|---|---|
| Node.js | >= 20.0.0 |
| npm / pnpm / yarn | Latest stable |
| OS | macOS, Linux, Windows (WSL2 recommended) |
# 1. Install globally
npm install -g @plumpslabs/fennec-cli
# 2. Install browser engines (Playwright Chromium)
fennec install-browsers
# 3. Generate config file (optional)
fennec initgit clone https://github.com/plumpslabs/fennec.git
cd fennec
pnpm install
pnpm build
npx playwright install chromium --with-depsFennec runs as an MCP server. Add this block to your MCP client's config file — the client will start Fennec automatically when needed:
{
"mcpServers": {
"fennec": {
"command": "fennec",
"args": ["start"]
}
}
}No need to manually run fennec start. The config file location varies by client:
| Client | Config File |
|---|---|
| Claude Desktop | claude_desktop_config.json |
| Claude Code | ~/.claude/settings.json |
| Cline (VS Code) | cline_mcp_settings.json |
| Cursor | .cursor/mcp.json |
| Windsurf | mcp_config.json |
| Continue.dev | config.json |
Or run the guided setup:
fennec setupTo test Fennec standalone (without an MCP client):
fennec startThen in another terminal:
npx @modelcontextprotocol/inspector fennec startOnce Fennec is running and connected to your AI agent, try this workflow:
# Terminal: Start your app with Fennec watching
npm run dev 2>&1 | fennec pipe --name "my-app"Then ask your AI agent:
"Check why my app is broken"
The AI will automatically use Fennec tools to:
- Open the browser to your app
- Check console errors
- Inspect failed network requests
- Correlate with server logs
- Report the root cause
| Step | What | Required? | Notes |
|---|---|---|---|
| 1 | Install Node.js >= 20 | ✅ Yes | nodejs.org |
| 2 | Install @plumpslabs/fennec-cli |
✅ Yes | npm install -g @plumpslabs/fennec-cli |
| 3 | Install Playwright browsers | ✅ Yes | fennec install-browsers (Chromium only) |
| 4 | MCP client (Claude Desktop, etc.) | ✅ Yes | For AI agent integration |
| 5 | Config file | Optional | fennec init for customization |
| 6 | Pipe server output | Optional | ` |
| 7 | Set env vars | Optional | See configuration docs |
We welcome contributions! See CONTRIBUTING.md for guidelines.
MIT — see LICENSE for details.
Built with ❤️ for AI-native development