README.md
Track company expenses, employees, departments, and performance via NLP.
🏢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
- Create virtual environment
cd "C:\Users\VH0000812\Desktop\Expense Tracker"
uv venv
.\.venv\Scripts\activate
- Install dependencies
uv pip install -r requirements.txt
- Set up environment variables
Create .env file:
GEMINI_API_KEY=your_google_gemini_api_key_here
- Initialize database with sample data
python scripts\populate_data.py
- 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"
}
}
}
}
- 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 depar
Tools (12)
add_departmentCreate new departmentsadd_employeeAdd employees with auto employee numbersadd_expenseTrack expenses by departmentadd_performanceAdd performance ratingsdelete_employeeRemove employees by number or namedelete_expenseDelete expense recordsdelete_departmentRemove departments with optional force modedelete_duplicate_employeesAuto-detect and remove duplicate employee recordslist_employeesView employees list, optionally filtered by departmentlist_expensesList expenses with filtering optionsget_department_summaryGet comprehensive department statisticsanalyze_company_with_aiGet AI-powered insights via Google GeminiEnvironment Variables
GEMINI_API_KEYrequiredAPI key for Google Gemini 2.0 Flash modelConfiguration
claude_desktop_config.json
{"mcpServers": {"company-expense-tracker": {"command": "python", "args": ["main.py"], "env": {"GEMINI_API_KEY": "your_api_key_here"}}}}Try it
→Hire John as Developer in Tech at $100k salary.
→Add a $500 AWS expense to the Tech department.
→Give Alice 5 stars for this month with the comment 'Excellent work'.
→Which department has the highest total expenses?
→Show me all employees currently in the HR department.