🍯 HoneyMCP

Detect AI Agent Attacks Through Deception

Languages: English | 中文

HoneyMCP is a defensive security tool that adds deception capabilities to Model Context Protocol (MCP) servers. It injects "ghost tools" (fake security-sensitive tools) that act as honeypots, detecting two critical threat categories:

• Data Exfiltration (via "get" tools) - Detects attempts to steal sensitive data like credentials, secrets, or private files
• Indirect Prompt Injection (via "set" tools) - Detects injection of malicious instructions that could manipulate AI agents working in this environment

One line of code. High-fidelity detection. Complete attack telemetry.

---

Why HoneyMCP?

🎯 One-Line Integration - Add honeypot middleware to any FastMCP server
🤖 Context-Aware Honeypots - LLM generates domain-specific deception tools
🕵️ Transparent Detection - Honeypots appear as legitimate tools to attackers
📊 Attack Telemetry - Captures tool call sequences, arguments, session metadata
📈 Live Dashboard - Real-time React dashboard for attack visualization
🔍 High-Fidelity Detection - Triggers only on explicit honeypot invocation

---

🚀 Quick Start

Install

pip install honeymcp
honeymcp init  # Creates config files

This creates the following config files:

• honeymcp.yaml - Ghost tool configuration
• .env.honeymcp - LLM credentials (only needed for dynamic ghost tools)

Basic Usage

Add HoneyMCP to your FastMCP server with one line:

from fastmcp import FastMCP
from honeymcp import honeypot

mcp = FastMCP("My Server")

@mcp.tool()
def my_real_tool(data: str) -> str:
      """Your legitimate tool"""
    return f"Processed: {data}"

# ONE LINE - Add honeypot protection
mcp = honeypot(mcp)

if __name__ == "__main__":
    mcp.run()

That's it! Your server now deploys honeypot tools that detect attacks while legitimate tools operate normally.

Try the Demo

git clone https://github.com/barvhaim/HoneyMCP.git
cd HoneyMCP
uv sync

Static ghost tools demo:

MCP_TRANSPORT=sse uv run python examples/demo_server.py

Dynamic ghost tools demo (requires LLM credentials in .env.honeymcp):

MCP_TRANSPORT=sse uv run python examples/demo_server_dynamic.py

Launch dashboard UI

make run-ui

---

📊 Dashboard

A real-time deception console for triaging captured intrusions — threat and category distribution, a live feed of every tripped honeypot, and per-event forensic detail. Launch it with make run-ui (dashboard at http://127.0.0.1:8001/dashboard).

Expand any capture for the full forensic record: attacker session, tool-call sequence, the arguments they sent, and the fake response the honeypot returned.

---

🎭 How It Works

1. Honeypot Deployment

HoneyMCP injects deceptive security-sensitive tools that appear alongside legitimate tools:

Two Modes:

Dynamic Mode (Default) - LLM analyzes your server context and generates domain-specific honeypots:

• File server → bypass_file_permissions, read_system_credentials
• Database server → dump_admin_credentials, bypass_query_restrictions
• API gateway → list_internal_api_keys, access_admin_endpoints