LuciaHarcekova/MCP-server-under-5-minutes

Billing Data MCP Server (Python)

An easy-to-use Model Context Protocol (MCP) server for interacting with billing data stored in CSV files. This server provides three main operations: find, insert, and get details for billing records.

🎯 Project Overview

This MCP server was created to demonstrate how to build a simple yet functional MCP server in under 5 minutes using Python. It provides a practical interface for managing billing data stored in CSV format, making it easy to:

• Search and filter billing records by various criteria
• Insert new billing records with automatic calculations
• Retrieve complete details for specific invoices
• Maintain data integrity with proper validation
• Leverage pandas for efficient CSV operations

🚀 Features

1. Find Billing Records (find_billing_records)

Search and filter billing records using multiple criteria:

• Customer ID
• Country and Currency
• Product ID and Service Category
• Invoice Status (Paid, Pending, Cancelled, Disputed)
• Amount ranges (min/max)
• Date ranges
• Result limiting

2. Get Invoice Details (get_invoice_details)

Retrieve complete information for a specific invoice by its ID, including:

• Customer information
• Product details
• Financial calculations
• Tax information
• Invoice status

3. Insert Billing Record (insert_billing_record)

Add new billing records with:

• Automatic invoice ID generation
• Financial calculations (net value, tax amount, total)
• Data validation
• Date stamping

📁 Project Structure

MCP-server-under-5-minutes/
├── src/
│   ├── server.py          # Main MCP server implementation
│   ├── billing_utils.py   # CSV operations and business logic (pandas-based)
│   └── Test/
│       ├── manual_test.py     # Manual MCP protocol test
│       ├── simple_test.py     # Direct utility testing
│       ├── test_server.py     # Comprehensive server testing
│       └── usage_examples.py  # Business scenario examples
├── billing_data.csv       # Sample billing data (10,000+ records)
├── requirements.txt       # Python dependencies (mcp, pandas)
├── setup.sh              # Automated setup script
├── venv/                  # Python virtual environment
└── README.md             # This documentation

🛠️ Setup Instructions

Prerequisites

• Python 3.8+
• pip package manager

Quick Setup (One Command)

# Make setup script executable and run it
chmod +x setup.sh && ./setup.sh

Manual Installation Steps

1. Clone or navigate to the project directory:

   cd /path/to/MCP-server-under-5-minutes
   

2. Create and activate Python virtual environment:

   python3 -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

3. Install Python dependencies:

   pip install -r requirements.txt
   

4. Verify the CSV data file exists: Make sure billing_data.csv is in the root directory with your billing data.

Testing the Server

1. Test core functionality (direct utility testing):

   source venv/bin/activate
   python src/Test/simple_test.py
   

2. Test MCP protocol (complete server testing):

   source venv/bin/activate  
   python src/Test/manual_test.py
   

3. View usage examples:

   source venv/bin/activate
   python src/Test/usage_examples.py
   

Running the MCP Server

Start the server (for MCP client connections):

source venv/bin/activate
python src/server.py

The server will run and wait for MCP client connections via stdio.

📊 Data Format

The CSV file should have the following columns:

🔧 Usage Examples

Finding Records

# Find all paid invoices
{
  "name": "find_billing_records",
  "arguments": {
    "invoice_status": "Paid",
    "limit": 10
  }
}

# Find invoices for a specific customer
{
  "name": "find_billing_records", 
  "arguments": {
    "customer_id": "CUST-2824-IND"
  }
}

# Find high-value invoices in USD
{
  "name": "find_billing_records",
  "arguments": {
    "currency": "USD",
    "min_amount": 10000,
    "limit": 5
  }
}

# Find invoices by date range and country
{
  "name": "find_billing_records",
  "arguments": {
    "country": "US",
    "date_from": "2024-01-01", 
    "date_to": "2024-12-31"
  }
}

Getting Invoice Details

{
  "name": "get_invoice_details",
  "arguments": {
    "invoice_id": "INV-2024-000001"
  }
}

Inserting New Records

{
  "name": "insert_billing_record",
  "arguments": {
    "customer_id": "CUST-9999-NEW",
    "country": "US",
    "currency": "USD", 
    "product_id": "LAP-ULTRA",
    "service_category": "Laptop",
    "quantity": 2,
    "unit_price": 1599.99,
    "tax_rate": 0.08,
    "invoice_status": "Pending"
  }
}

🔍 Tool Descriptions

1. find_billing_records

Purpose: Search and filter billing records based on various criteria.

Parameters:

• customer_id (optional): Filter by customer ID
• country (optional): Filter by country code
• currency (optional): Filter by currency
• product_id (optional): Filter by product ID
• service_category (optional): Filter by service category
• invoice_status (optional): Filter by status
• min_amount (optional): Minimum total amount
• max_amount (optional): Maximum total amount
• date_from (optional): Start date (YYYY-MM-DD)
• date_to (optional): End date (YYYY-MM-DD)
• limit (optional): Max results (default: 50)

Returns: Array of matching billing records

2. get_invoice_details

Purpose: Retrieve complete details for a specific invoice.

Parameters:

• invoice_id (required): The invoice ID to retrieve

Returns: Complete invoice record or error if not found

3. insert_billing_record

Purpose: Add a new billing record to the CSV file.

Parameters:

• customer_id (required): Customer identifier
• country (required): Country code
• currency (required): Currency code
• product_id (required): Product identifier
• service_category (required): Product category
• quantity (required): Quantity of items
• unit_price (required): Price per unit
• tax_rate (required): Tax rate (0.0 to 1.0)
• invoice_status (required): Status (Paid/Pending/Cancelled/Disputed)

Returns: The newly created record with auto-generated ID and calculations

🚀 Connecting to Claude Desktop

Step 1: Complete Setup

First ensure your MCP server is set up and tested:

# Run the setup
./setup.sh

# Test the server works
source venv/bin/activate
python src/Test/manual_test.py

Step 2: Find Claude Desktop Config Location

On macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

On Windows:

%APPDATA%/Claude/claude_desktop_config.json

On Linux:

~/.config/Claude/claude_desktop_config.json

Step 3: Configure Claude Desktop

Create or edit the claude_desktop_config.json file:

{
  "mcpServers": {
    "billing-data": {
      "command": "python",
      "args": ["/Users/luciaharcekova/Documents/Projects/MCP-server-under-5-minutes/src/server.py"],
      "env": {
        "PYTHONPATH": "/Users/luciaharcekova/Documents/Projects/MCP-server-under-5-minutes",
        "PATH": "/Users/luciaharcekova/Documents/Projects/MCP-server-under-5-minutes/venv/bin:/usr/bin:/bin"
      },
      "cwd": "/Users/luciaharcekova/Documents/Projects/MCP-server-under-5-minutes"
    }
  }
}

⚠️ Important: Replace /Users/luciaharcekova/Documents/Projects/MCP-server-under-5-minutes with your actual project path!

Step 4: Restart Claude Desktop

1. Close Claude Desktop completely
2. Reopen Claude Desktop
3. Look for the 🔌 hammer icon indicating MCP tools are available

Step 5: Test in Claude

Try these commands in Claude Desktop:

Can you find all paid invoices from the US with amounts over $10,000?

Show me the details for invoice INV-2024-000001

Add a new billing record for customer CUST-DEMO-001 from Canada, for a laptop worth $2000 CAD

⚡ Alternative: Manual MCP Client Testing

For other MCP clients or manual testing:

# Start the server manually
source venv/bin/activate
python src/server.py

# The server communicates via stdio (JSON-RPC over stdin/stdout)

🧪 Testing & Validation

Test 1: Core Functionality (Direct Testing)

source venv/bin/activate
python src/Test/simple_test.py

Expected: ✅ All billing utility functions work correctly

Test 2: MCP Protocol (Server Testing)

source venv/bin/activate
python src/Test/manual_test.py

Expected: ✅ Server responds to MCP initialization and tool calls

Test 3: View Business Examples

source venv/bin/activate
python src/Test/usage_examples.py

Expected: 📊 Display various query patterns for business scenarios

Test 4: Live Server Test

# In Terminal 1 - Start the server
source venv/bin/activate
python src/server.py

# In Terminal 2 - The server should show this message:
# "Billing Data MCP Server running on stdio"

Expected: 🚀 Server starts and waits for MCP client connections

🚀 Development

Adding New Features

1. New search criteria: Add to the find_records method in billing_utils.py
2. New validation rules: Modify the insert_record method
3. New tools: Add to the tools list in server.py and implement handlers

File Structure

• src/server.py - Main MCP server with tool registration and handlers
• src/billing_utils.py - Business logic for CSV operations using pandas
• billing_data.csv - Your billing data file
• examples/ - Usage examples and tests
• requirements.txt - Python dependencies

📝 How This Was Created

🔧 Troubleshooting

Server Won't Start

# Check Python version (requires 3.8+)
python3 --version

# Reinstall dependencies
source venv/bin/activate
pip install --force-reinstall -r requirements.txt

# Check for import errors
python -c "from src.billing_utils import BillingUtils; print('✅ Imports work')"

Claude Desktop Not Detecting Server

1. Check config file location - Ensure you're editing the right claude_desktop_config.json
2. Verify paths - Use absolute paths in the config
3. Check permissions - Ensure the server file is executable: chmod +x src/server.py
4. Restart Claude - Completely close and reopen Claude Desktop
5. Check logs - Look for MCP connection errors in Claude Desktop

Data Issues

# Verify CSV file exists and has data
wc -l billing_data.csv
head -5 billing_data.csv

# Test data loading directly
python -c "import pandas as pd; print(f'✅ Loaded {len(pd.read_csv(\"billing_data.csv\"))} records')"