CryptoJym/freshbooks-mcp-server

🚀 FreshBooks Inventory MCP Server

✨ Features

🔐 OAuth 2.0 Authentication - Secure FreshBooks API integration with automatic token refresh
📦 Full CRUD Operations - Create, read, update, delete inventory items
🔍 Advanced Search - Find items by SKU, description, or inventory levels
⚡ Bulk Operations - Update multiple items simultaneously
🛡️ Robust Error Handling - Comprehensive validation and clear error messages
📊 Inventory Management - Track stock levels, costs, and product details
🧪 Production Ready - Tested, documented, and ready for deployment

🚀 Quick Start

Prerequisites

• Python 3.10+
• A FreshBooks account with developer access
• An MCP-compatible client (like Claude Desktop)

1️⃣ Clone & Install

# Clone the repository
git clone https://github.com/h3ro-dev/freshbooks-mcp-server.git
cd freshbooks-mcp-server

# Install dependencies
pip install -r requirements.txt

2️⃣ FreshBooks App Setup

1. Go to FreshBooks Developer Portal
2. Create a new application
3. Set redirect URI to: http://localhost:8080/callback
4. Save your Client ID and Client Secret

3️⃣ Environment Configuration

# Copy the example environment file
cp .env.example .env

# Edit with your credentials
nano .env

Add your FreshBooks credentials:

FRESHBOOKS_CLIENT_ID=your_client_id_here
FRESHBOOKS_CLIENT_SECRET=your_client_secret_here
FRESHBOOKS_REDIRECT_URI=http://localhost:8080/callback

4️⃣ Authentication Flow

# Start the server
python freshbooks_server.py

# In another terminal, get authorization URL
mcp call get_authorization_url

# Visit the URL, authorize, then exchange the code
mcp call exchange_authorization_code '{"authorization_code": "your_code_here"}'

Add the returned tokens to your .env:

FRESHBOOKS_ACCESS_TOKEN=your_access_token_here
FRESHBOOKS_REFRESH_TOKEN=your_refresh_token_here
FRESHBOOKS_ACCOUNT_ID=your_account_id_here

5️⃣ Test Your Setup

# List your inventory items
mcp call list_items

# Create a test item
mcp call create_item '{
  "item_data": {
    "name": "Test Product",
    "sku": "TEST-001",
    "inventory": "100"
  }
}'

🛠️ Available Tools

📚 Documentation

• - Detailed tool documentation
• - Comprehensive examples and workflows
• - Validation and error management

🎯 Common Use Cases

Inventory Restock Workflow

# Check low inventory
mcp call get_low_inventory_items '{"threshold": 20}'

# Bulk update restocked items
mcp call bulk_update_inventory '{
  "updates": [
    {"item_id": 123, "inventory": "100"},
    {"item_id": 124, "inventory": "75"}
  ]
}'

Product Search & Update

# Find product by SKU
mcp call search_items_by_sku '{"sku": "LAPTOP-001"}'

# Update inventory count
mcp call update_inventory_count '{"item_id": 123, "new_count": "85"}'

🔧 Development

Run Tests

python test_server.py

Code Quality

# Format code
black freshbooks_server.py error_handling.py

# Type checking
mypy freshbooks_server.py

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit changes: git commit -m 'Add amazing feature'
4. Push to branch: git push origin feature/amazing-feature
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the file for details.

🆘 Support

• 📖 Check the first
• 🐛 Report bugs
• 💡 Request features
• 💬 Discussions