🏢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)

Tool	Description	Example
add_department	Create new departments	"Create Marketing department"
add_employee	Add employees with auto employee numbers	"Hire John as Developer in Tech at $100k"
add_expense	Track expenses by department	"Add $500 AWS expense to Tech"
add_performance	Add performance ratings	"Give Alice 5 stars this month"

🗑️ Delete Operations (4)

Tool	Description	Example
delete_employee	Remove employees by number/name	"Delete employee EMP0015"
delete_expense	Delete expense records	"Delete expense ID 45"
delete_department	Remove departments (force mode available)	"Force delete Marketing with all data"
delete_duplicate_employees	Auto-detect and remove duplicates	"Remove all duplicate employees"

📋 Query Operations (3)

Tool	Description	Example
list_employees	View employees (all or by department)	"Show all HR employees"
list_expenses	List expenses with filters	"Show Tech expenses last 30 days"
get_department_summary	Comprehensive department stats	"Give me HR summary"

🤖 AI Analysis (1)

Tool	Description	Example
analyze_company_with_ai	AI-powered insights via Gemini	"Which department spends most?"

💬 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