🏢Enterprise Expense Automation System using MCP & NLP

A professional Model Context Protocol (MCP) server for tracking company expenses, employees, departments, and performance through natural language conversations with Claude Desktop.

✨ Features

• 12 MCP Tools for complete CRUD operations

• Natural Language Interface through Claude Desktop chatbot

• Employee Management with unique employee numbers (EMP0001, EMP0002, etc.)

• Expense Tracking with categorization and department assignment

• Performance Management with ratings and comments

• AI-Powered Analysis using Google Gemini 2.0 Flash (Latest 2025 Model)

• Duplicate Detection and automatic cleanup

• Safe Delete Operations with cascade support

🏗️ System Architecture

The architecture shows the complete flow from Claude Desktop through the MCP Server to the SQLite database, with AI-powered analysis via Google Gemini.

📊 Database Schema

departments         employees              expenses              performance
├── id             ├── id                 ├── id                ├── id
├── name           ├── employee_number    ├── date              ├── employee_id
└── description    ├── name               ├── amount            ├── rating
                   ├── role               ├── category          ├── month
                   ├── department_id      ├── note              └── comments
                   ├── salary             └── department_id
                   └── join_date

Current Data:

• 4 Departments (Admin, HR, Tech, BPO)

• 18 Employees with unique employee numbers

• 34 Expense records

• 20 Performance ratings

🚀 Quick Start

Prerequisites

• Python 3.11 or higher

• UV package manager or pip

• Claude Desktop application

• Google Gemini API key

Installation

1. Create virtual environment

cd "C:\Users\VH0000812\Desktop\Expense Tracker"
uv venv
.\.venv\Scripts\activate

2. Install dependencies

uv pip install -r requirements.txt

3. Set up environment variables

Create .env file:

GEMINI_API_KEY=your_google_gemini_api_key_here

4. Initialize database with sample data

python scripts\populate_data.py

5. Configure Claude Desktop

Add to %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "company-expense-tracker": {
      "command": "C:\\Users\\VH0000812\\Desktop\\Expense Tracker\\.venv\\Scripts\\python.exe",
      "args": [
        "C:\\Users\\VH0000812\\Desktop\\Expense Tracker\\main.py"
      ],
      "env": {
        "GEMINI_API_KEY": "your_api_key_here"
      }
    }
  }
}

6. Restart Claude Desktop

🛠️ MCP Tools (12 Total)

➕ Create Operations (4)

🗑️ Delete Operations (4)

📋 Query Operations (3)

🤖 AI Analysis (1)

💬 Usage Examples

Employee Management

✅ "Hire Sarah as Marketing Manager in Admin at $75,000"
✅ "Show me all Tech department employees"
✅ "Delete employee EMP0017"
✅ "Find and remove all duplicate employees"

Expense Tracking

✅ "Add $1,500 office furniture expense to Admin"
✅ "Show all expenses from last month"
✅ "Delete expense ID 32"

Performance & Analysis

✅ "Give John Smith a 5-star rating with comment 'Excellent work'"
✅ "Show me complete HR department summary"
✅ "Which department has highest salary burden?"
✅ "Analyze expense trends across departments"

📁 Project Structure

Expense Tracker/
├── src/                      # Source code modules
│   ├── operations/           # Business logic
│   ├── ai/                   # AI integration
│   ├── tools/                # MCP tool definitions
│   ├── database.py           # Database config
│   └── __init__.py
├── tests/                    # All test files
│   ├── test_tools.py
│   ├── test_delete_functions.py
│   └── test_employee_numbers.py
├── scripts/                  # Utility scripts
│   ├── populate_data.py      # Initialize data
│   ├── migrate_employee_numbers.py
│   └── db_viewer.py          # Interactive viewer
├── docs/                     # Documentation
│   ├── QUICK_REFERENCE.md
│   ├── DELETE_TOOLS.md
│   └── COMPLETE_SUMMARY.md
├── config/                   # Configuration
│   └── departments.json
├── data/                     # Database
│   └── company.db
├── main.py                   # Entry point
├── requirements.txt
├── .env
├── .gitignore
└── README.md

🧪 Testing

Run tests:

python tests\test_tools.py
python tests\test_delete_functions.py
python tests\test_employee_numbers.py

Interactive database viewer:

python scripts\db_viewer.py

🔧 Configuration

Expense Categories

• Infrastructure, Software Licenses, Training

• Office Supplies, Utilities, Salaries

• Recruitment, Events, Equipment, Maintenance

Employee Number Format

• Auto-generated: EMP0001, EMP0002, etc.

• Unique identifier for each employee

• Used for quick lookups and operations

🔒 Security Features

• ✅ API keys in environment variables

• ✅ Foreign key constraints in database

• ✅ Input validation on all operations

• ✅ Safe delete mode (force flag required for cascade)

• ✅ Duplicate detection and prevention

🆘 Troubleshooting

Claude Desktop not showing tools

1. Restart Claude Desktop (right-click tray icon → Quit)

2. Check config path in claude_desktop_config.json

3. Verify database exists at data/company.db

Database errors

# Migrate employee numbers
python scripts\migrate_employee_numbers.py

# Reinitialize database
python scripts\populate_data.py

Import errors

# Reinstall dependencies
uv pip install -r requirements.txt

# Check Python version (must be 3.11+)
python --version

📚 Documentation

• Quick Reference: docs/QUICK_REFERENCE.md

• Complete Summary: docs/COMPLETE_SUMMARY.md

• Delete Tools Guide: docs/DELETE_TOOLS.md

• Getting Started: docs/GETTING_STARTED.md

🎯 Roadmap

• Update/edit operations for employees and expenses

• Bulk import/export functionality

• Monthly and yearly report generation

• Budget tracking with alerts

• Employee search by skills/role

• Expense approval workflow

• Department budget management

• API endpoint version

📈 Statistics

🏢 Departments:        4 (Admin, HR, Tech, BPO)
👥 Employees:          18 (with unique employee numbers)
💰 Total Salary:       $1,288,000 annually
💳 Expense Records:    34 tracked
⭐ Performance:        20 ratings (avg 4.2/5.0)

🤝 Development

Adding New Tools

1. Define function in appropriate module

2. Add MCP tool wrapper in main.py

3. Test with tests/test_*.py

4. Update documentation

Code Style

• Follow PEP 8 guidelines

• Use type hints

• Add docstrings to all functions

• Include error handling

📝 License

Internal use only - Company Expense Tracker

Version: 1.0.0
Last Updated: October 15, 2025
Status: ✅ Production Ready
Maintained by: Company Development Team

For support or questions, see docs/COMPLETE_SUMMARY.md