honeydb-ai 0.2.3

HoneyDB AI Interface with HoneyDB MCP Server

HoneyDB MCP CLI

MCP-Enabled Threat Intelligence Chat Interface

Overview

HoneyDB MCP CLI is a command-line interface that connects your favorite LLM (OpenAI, Anthropic, or Gemini) with HoneyDB's threat intelligence tools via the Model Context Protocol (MCP). Ask natural language questions about IP addresses, payloads, honeypot data, and more—your LLM automatically invokes HoneyDB tools to provide accurate, real-time threat intelligence.

What is MCP?

The Model Context Protocol allows LLMs to access external tools and data sources. This CLI connects to the HoneyDB MCP server, which exposes 20+ threat intelligence tools that LLMs can invoke autonomously during conversations.

Supported LLM Providers

• OpenAI
• Anthropic
• Google Gemini

Features

Core Features

• 🔧 MCP Tool Integration - LLMs can invoke HoneyDB tools automatically
• 💬 Interactive Chat - Natural language interface to threat intelligence data
• 💾 Session Management - Save, resume, and manage multiple chat sessions
• 🎨 Professional UI - Dark/light mode, animated thinking indicator, error handling
• 🐝 Thinking Indicator - Animated bee/honeypot-themed feedback while the LLM processes requests, with graceful fallback for non-interactive terminals

HoneyDB MCP Tools Available

• IP Intelligence - Scanner detection, history, network enrichment
• Monitors - Create, view, and delete threat monitors
• Honeypot Nodes - Node management and data retrieval
• Statistics - Threat data aggregation and analysis
• Bad Host Tracking - Recent malicious activity monitoring

Recent Enhancements

• ✅ MCP Integration - Full MCP protocol support with HoneyDB server
• 🔒 Enhanced Security - File locking prevents data corruption
• ⌨️ Graceful Interruption - Ctrl+C cancellation without data loss
• 🎯 Terminal Detection - Automatic dark/light mode support
• 🔐 Privacy-First Logging - Never logs API keys or message content
• 🔄 Hot Configuration Reload - Update settings without restarting
• 📑 Session Pagination - Efficiently manage thousands of sessions
• 🐝 Thinking Indicator - Animated bee/honeypot-themed feedback while awaiting LLM responses
• 🤖 Updated LLM Models - Current flagship models set as defaults: GPT-5.4 (OpenAI), Claude Opus 4.6 (Anthropic), Gemini 3.1 Pro (Gemini)

Installation

Requirements

• Python 3.10 or newer
• HoneyDB API credentials (sign up at honeydb.io)
• At least one LLM provider API key (OpenAI, Anthropic, or Gemini)

Install with pip

git clone https://github.com/honeydbio/mcp-cli.git
cd mcp-cli

# Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies and the package
pip install -r requirements.txt
pip install .

Install with uv (Faster Alternative)

uv is a fast drop-in replacement for pip and venv. Installation steps are identical — substitute uv for pip and python -m venv:

git clone https://github.com/honeydbio/mcp-cli.git
cd mcp-cli

uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

uv pip install -r requirements.txt
uv pip install .

Install with pipx

git clone https://github.com/honeydbio/mcp-cli.git
cd mcp-cli
pipx install .

Quick Start

1. Interactive Setup (Recommended)

Run the setup wizard to configure everything at once:

honeydb-ai config setup

The wizard will prompt you for:

1. HoneyDB API credentials (required for MCP tools)

   • API ID
   • API Key
   • Get them at: https://honeydb.io/

2. LLM Provider (choose one)

   • OpenAI (recommended)
   • Anthropic
   • Google Gemini

3. MCP Server

   • Production (default): https://honeydb.ai/sse
   • Development (optional): For testing

4. UI Preferences

   • Theme (auto-detect, dark, light)
   • Verbose tool calls (show MCP tool invocations)

2. Manual Configuration

Set credentials individually:

# HoneyDB credentials (REQUIRED)
honeydb-ai config set honeydb_api_id your-api-id
honeydb-ai config set honeydb_api_key your-api-key

# LLM Provider API Key (at least one REQUIRED)
honeydb-ai config set openai_api_key sk-your-key-here
# OR
honeydb-ai config set anthropic_api_key sk-ant-your-key-here
# OR
honeydb-ai config set gemini_api_key your-key-here

# Optional: Set default provider
honeydb-ai config set default_provider openai

# Optional: Use development MCP server
honeydb-ai config set mcp_server_url https://honeydb-mcp-dev-db384193f137.herokuapp.com/sse

3. Start Chatting

honeydb-ai chat

Usage Examples

Basic Threat Intelligence Queries

> What threats has IP 1.2.3.4 been involved in?
🔧 Tool Call: get_internet_scanner(ip_address="1.2.3.4")
🔧 Tool Call: get_ip_history(ip_address="1.2.3.4")

HoneyDB: IP 1.2.3.4 is identified as an internet scanner and has been
observed in 42 malicious activities across our honeypot network...

---

> Show bad hosts for the service MSSQL
🔧 Tool Call: get_bad_hosts(service="MSSQL")

HoneyDB: Here are the most recent bad hosts targeting MSSQL:
- 198.51.100.42 — 17 attempts, last seen 2026-03-17
- 203.0.113.88 — 9 attempts, last seen 2026-03-16
...

---

> Create a monitor for IP range 10.0.0.0/24
🔧 Tool Call: put_monitors(type="ip_range", range=["10.0.0.0", "10.0.0.255"])

HoneyDB: ✅ Monitor created successfully for IP range 10.0.0.0/24

Session Management

# Start a new session
honeydb-ai chat --new

# Resume a previous session
honeydb-ai sessions list
honeydb-ai chat --session <session-id>

# View session history
honeydb-ai sessions show <session-id>

# Export session
honeydb-ai sessions export <session-id> output.json
honeydb-ai sessions export <session-id> output.md --format markdown

# Delete old sessions
honeydb-ai sessions delete <session-id>

Configuration Management

# View current configuration
honeydb-ai config show

# Show config file location
honeydb-ai config path

# Update settings
honeydb-ai config set temperature 0.8
honeydb-ai config set theme dark
honeydb-ai config set default_model gpt-5.4

Chat Commands

While in chat mode, the following slash commands are available:

Command	Description
/help	Show available commands
/exit or /quit	Exit chat mode and return to the shell
/model	Show current provider, model, and session stats
/model change	Interactively switch provider and model
/history	Display the current session's message history
/new	Start a new chat session

Note: Typing exit or quit without the leading / will not exit — the CLI will remind you to use /exit or /quit.

---

MCP Tool Call Visibility

By default, MCP tool calls are hidden to keep chat clean. Enable verbose mode to see tool invocations:

During Setup:

Show MCP tool calls during chat? (y/N): y

Or Configure Later:

honeydb-ai config set verbose_tool_calls true

When Enabled:

> Check IP 8.8.8.8
🔧 Tool Call: get_internet_scanner(ip_address="8.8.8.8", info=True)
✅ Tool Result: get_internet_scanner
🔧 Tool Call: get_ip_history(ip_address="8.8.8.8")
✅ Tool Result: get_ip_history

HoneyDB: [response incorporating tool results]

Architecture

MCP Flow Diagram

User Input
    ↓
CLI Application (honeydb-ai)
    ↓
LLM Provider (OpenAI/Anthropic/Gemini)
    ↓ (recognizes need for HoneyDB data)
HoneyDB MCP Server (https://honeydb.ai/sse)
    ↓ (authenticated with HoneyDB API credentials)
HoneyDB REST API (https://honeydb.io/api/)
    ↓ (retrieves threat intelligence data)
MCP Server returns results to LLM
    ↓
LLM incorporates data into response
    ↓
CLI displays formatted response to user

Key Components

• MCP Adapters (infrastructure/mcp/) - Provider-specific MCP integrations
• LLM Service (services/llm_service.py) - Unified interface to all providers
• Session Management (services/session_service.py) - Chat history persistence
• Configuration (infrastructure/storage/config_store.py) - INI-based settings
• Rich UI (infrastructure/ui/) - Terminal rendering and prompts

Configuration File

Located at: ~/.honeydb_ai/config.ini

[honeydb]
api_id = your-honeydb-api-id
api_key = your-honeydb-api-key
mcp_server_url = https://honeydb.ai/sse

[llm]
default_provider = openai
openai_api_key = sk-...
anthropic_api_key =
gemini_api_key =
default_model = gpt-5.4
temperature = 0.7
max_tokens =

[session]
auto_save = true
sessions_dir = ~/.honeydb_ai/sessions

[ui]
theme = auto
markdown_enabled = true
syntax_highlighting = true
verbose_tool_calls = false

[logging]
log_level = INFO
log_file = ~/.honeydb_ai/honeydb_ai.log
log_max_size_mb = 5
log_backup_count = 3

Troubleshooting

"HoneyDB API credentials not configured"

Solution:

honeydb-ai config set honeydb_api_id your-id
honeydb-ai config set honeydb_api_key your-key

Get credentials at: https://honeydb.io/

"No LLM provider API keys configured"

Solution: Configure at least one LLM provider:

honeydb-ai config set openai_api_key sk-...
# OR
honeydb-ai config set anthropic_api_key sk-ant-...
# OR
honeydb-ai config set gemini_api_key ...

MCP Tools Not Working

1. Check HoneyDB credentials are set:

   honeydb-ai config show
   

2. Verify MCP server URL:

   # Should be: https://honeydb.ai/sse (production)
   # Or: https://honeydb-mcp-dev-db384193f137.herokuapp.com/sse (dev)
   honeydb-ai config set mcp_server_url https://honeydb.ai/sse
   

3. Enable verbose mode to see tool calls:

   honeydb-ai config set verbose_tool_calls true
   

Session Corruption

If a session file is corrupted, the CLI will attempt to restore from backup (.bak file). If both are corrupted:

# Delete the corrupted session
honeydb-ai sessions delete <session-id>

# Start a new session
honeydb-ai chat --new

Development

Running Tests

# Create and activate virtual environment
uv venv
source .env/bin/activate  # On Windows: .env\Scripts\activate

# Install development dependencies
uv pip install -e ".[dev]"

# Run tests
pytest

# Run with coverage
pytest --cov=honeydb_ai

Testing MCP Integration

# Use development MCP server
honeydb-ai config set mcp_server_url https://honeydb-mcp-dev-db384193f137.herokuapp.com/sse

# Enable verbose mode to see tool calls
honeydb-ai config set verbose_tool_calls true

# Test with a simple query
honeydb-ai chat
You: Hello
# Should invoke the 'hello' greeting tool

Project Structure

honeydb_ai/
├── cli/                    # CLI commands and entry points
├── controllers/            # Business logic controllers
├── domain/                 # Domain models and interfaces
├── infrastructure/         # External integrations
│   ├── mcp/               # MCP adapter implementations
│   ├── storage/           # File storage (sessions, config)
│   └── ui/                # Terminal UI components
├── services/              # Service layer (LLM, sessions, config)
└── utils/                 # Utilities (logging, formatting, validation)

Contributing

Contributions are welcome! Please:

1. Fork the repository
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

This software is proprietary and confidential. All rights reserved by Deception Logic. See the LICENSE file for details.

Related Resources

• HoneyDB Platform: https://honeydb.io/
• HoneyDB API Documentation: https://honeydb.io/api/
• MCP Specification: https://spec.modelcontextprotocol.io/
• MCP Server Source: /home/foospidy/github.com/honeydbio/mcp-server/

Support

• Issues: https://github.com/honeydbio/mcp-cli/issues
• Discussions: https://github.com/honeydbio/mcp-cli/discussions
• HoneyDB Support: [e-mail]

Acknowledgments

• Built with FastMCP for MCP client support
• Uses Rich for beautiful terminal output
• Powered by Typer for CLI framework
• Uses prompt_toolkit for interactive prompts

---

Made with ❤️ by the HoneyDB Team