mcp-marketing-demo

NimbleBrainInc/mcp-marketing-demo

3.2

If you are the rightful owner of mcp-marketing-demo and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The Coffee Marketing Analytics MCP Server is an advanced retail analytics server designed to optimize coffee sales through data-driven insights.

Tools
3
Resources
0
Prompts
0

Coffee Marketing Analytics MCP Server

An advanced retail analytics MCP (Model Context Protocol) server that analyzes coffee sales data to optimize product placement, inventory allocation, and marketing strategies. Built for real-world retail decision-making with machine learning insights.

Overview

This MCP server transforms raw retail data into actionable business intelligence by analyzing:

  • Product performance across different store locations and placements
  • Sales velocity and inventory optimization recommendations
  • Store characteristics and regional performance patterns
  • Brand performance and competitive insights
  • Promotional effectiveness and pricing strategies

Features

Core Analytics Functions

  • get_sales_insights - Comprehensive sales analysis with brand, regional, and promotional breakdowns
  • identify_best_product - Recommends optimal products for specific inventory quantities and timeframes
  • identify_best_stores - Identifies top-performing stores and analyzes success factors

Key Capabilities

  • Inventory Optimization: Determine which products to stock and where
  • Sales Velocity Analysis: Calculate how quickly products will sell in specific locations
  • Store Performance Ranking: Identify and replicate success patterns
  • Brand & Category Analysis: Track performance across product attributes
  • Feasibility Scoring: Assess likelihood of meeting sales targets

Dataset

The server analyzes a comprehensive Hawaiian coffee retail dataset including:

  • 139,880 sales records across 48 stores and 180 products
  • Store characteristics: Location, format, affluence index, foot traffic
  • Product attributes: Brand, origin, roast, grind, size, organic certification
  • Placement data: Shelf level, eye-level distance, facings, adjacencies
  • Promotional data: Discounts, displays, end-cap placement
  • Sales metrics: Units sold, revenue, pricing over 52 weeks

Installation

Prerequisites

  • Python 3.8+
  • pandas, numpy, scikit-learn
  • MCP-compatible client (Claude Desktop, etc.)

Setup Steps

  1. Clone and setup project:
git clone <repository-url>
cd mcp-marketing-demo
python -m venv marketing-demo-env

# Activate virtual environment
# Windows:
marketing-demo-env\Scripts\activate
# macOS/Linux:
source marketing-demo-env/bin/activate
  1. Install dependencies:
pip install pandas numpy scikit-learn
  1. Verify data files: Ensure these CSV files are in the data/ directory:
  • coffee_products.csv
  • coffee_stores.csv
  • coffee_placements.csv
  • coffee_adjacencies.csv
  • coffee_prices_promos.csv
  • coffee_sales.csv
  1. Test server:
python coffee_marketing_mcp_server.py

Server should start and wait silently for MCP communication.

  1. Configure MCP client: Add to your MCP client configuration:
{
  "mcpServers": {
    "coffee-marketing": {
      "command": "python",
      "args": ["path/to/mcp-marketing-demo/coffee_marketing_mcp_server.py"],
      "cwd": "path/to/mcp-marketing-demo"
    }
  }
}

Usage Examples

Inventory Planning

Question: "I need to stock 500 units at store 15 over the next 6 weeks. What product should I choose?"

Function: identify_best_product

{
  "store_id": 15,
  "target_units": 500,
  "weeks_to_sell": 6
}

Output: Ranked product recommendations with feasibility scores, sales velocity, and projected performance.

Store Performance Analysis

Question: "Which stores should I prioritize for my premium coffee launch?"

Function: identify_best_stores

{
  "metric": "revenue"
}

Output: Store rankings with performance metrics, regional insights, and success factors.

Brand Performance Review

Question: "Give me a comprehensive analysis of brand performance across all stores."

Function: get_sales_insights

{
  "analysis_type": "brand"
}

Output: Brand-by-brand performance breakdown with revenue, volume, and pricing analysis.

Data Insights

Sample Findings

  • 139,880 total sales records spanning 52 weeks
  • 48 unique stores across multiple regions and formats
  • 180 distinct products with varied attributes and positioning
  • Shelf placement impact: Eye-level products show 15-25% higher velocity
  • Regional variations: Store format and affluence significantly impact performance
  • Promotional effectiveness: Varies dramatically by product category and store type

Business Applications

  • Reduce inventory waste by stocking products with highest sales probability
  • Optimize shelf space allocation based on performance data
  • Identify expansion opportunities by replicating successful store characteristics
  • Improve promotional ROI through targeted placement strategies

Architecture

Data Processing Pipeline

  1. Data Ingestion: Loads and validates CSV files from data directory
  2. Data Merging: Combines sales, product, store, and placement data
  3. Analytics Engine: Applies statistical analysis and ML algorithms
  4. MCP Interface: Exposes functions via JSON-RPC protocol

Technical Implementation

  • Pandas/NumPy: Data manipulation and statistical analysis
  • Scikit-learn: Machine learning for predictive modeling
  • Async Python: Non-blocking MCP server implementation
  • JSON-RPC: Standard protocol for MCP communication

Development

File Structure

mcp-marketing-demo/
ā”œā”€ā”€ coffee_marketing_mcp_server.py    # Main server implementation
ā”œā”€ā”€ data/                             # CSV data files
ā”‚   ā”œā”€ā”€ coffee_products.csv
ā”‚   ā”œā”€ā”€ coffee_stores.csv
ā”‚   ā”œā”€ā”€ coffee_placements.csv
ā”‚   ā”œā”€ā”€ coffee_adjacencies.csv
ā”‚   ā”œā”€ā”€ coffee_prices_promos.csv
ā”‚   ā””ā”€ā”€ coffee_sales.csv
ā”œā”€ā”€ requirements.txt                  # Python dependencies
ā””ā”€ā”€ README.md                        # This file

Function Overview

Core Analytics:

  • get_sales_insights: Brand performance, overall metrics, and sales breakdowns
  • identify_best_product: Product recommendations for specific inventory and timeline requirements

Optimization:

  • analyze_shelf_placement: Shelf positioning, eye-level impact, and adjacency effectiveness
  • analyze_store_performance: Store ranking, characteristics analysis, and success factors

Intelligence:

  • analyze_market_dynamics: Market share, customer preferences, and competitive analysis
  • analyze_promotional_impact: Discount optimization, display effectiveness, and promotional ROI

Advanced Features

The server is designed for extensibility and supports:

  • Flexible analysis types for each function (specific focus areas or comprehensive "all" analysis)
  • Configurable parameters (limits, thresholds, analysis depth)
  • Statistical correlation analysis and performance lift calculations
  • Data-driven recommendations with quantified business impact

Testing

Run basic functionality tests:

# Test data loading
python -c "from coffee_marketing_mcp_server import CoffeeMarketingAnalytics; c=CoffeeMarketingAnalytics(); print('Success' if c.load_data() else 'Failed')"

# Test server startup
python coffee_marketing_mcp_server.py

Troubleshooting

Common Issues

  • "No such file or directory": Ensure CSV files are in data/ directory
  • "Failed to load data": Check file permissions and CSV format
  • "Server disconnected": Verify Python dependencies are installed

Debug Mode

For detailed error output, run server with:

python coffee_marketing_mcp_server.py 2>error.log

Performance

  • Data processing: ~2-3 seconds for full dataset load and merge
  • Query response: <1 second for most analytics functions
  • Memory usage: ~200-300MB for full dataset in memory
  • Concurrent requests: Handles multiple MCP client connections

License

MIT License - See LICENSE file for details.

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests for new functionality
  5. Submit a pull request

Support

For issues, questions, or feature requests, please create an issue in the GitHub repository.

Built for real-world retail analytics - Transform your sales data into competitive advantage.