AI2Fin MCP integration code examples

Production-ready code examples for integrating with the AI2Fin Finance MCP server. Learn how to connect ChatGPT, Claude, or your own AI agents to your financial data for expense tracking, tax-deduction analysis, bill management, and financial reporting — in Python and TypeScript.

Tax & Deductions

Tax deduction analysis examples

Expense Tracking

Spending analysis and tracking

Bill Management

Recurring bill automation

Receipt Processing

Automated receipt handling

ChatGPT Integration

Connect ChatGPT to finances

Custom AI Agents

Build financial AI assistants

Example 1: Tax Deduction Analysis

Use Case: Get comprehensive tax deduction report for financial year User Intent: “I need to know what expenses are tax deductible for my business tax return”

Python - Using MCP Protocol

import requests

# Your AI2Fin JWT token or API key
TOKEN = "eyJhbGciOiJIUzI1NiIs..."  # JWT token
# OR
API_KEY = "mcp_a1b2c3d4e5f6..."  # API key for /mcp/inspector

BASE_URL = "https://api.ai2fin.com"

def get_tax_deductible_summary(start_date: str, end_date: str, use_api_key: bool = False):
    """Get tax deductible expenses summary using MCP"""
    endpoint = "/mcp/inspector" if use_api_key else "/mcp"
    auth_header = "X-API-Key" if use_api_key else "Authorization"
    auth_value = API_KEY if use_api_key else f"Bearer {TOKEN}"
    
    response = requests.post(
        f"{BASE_URL}{endpoint}",
        headers={
            auth_header: auth_value,
            "Content-Type": "application/json"
        },
        json={
            "jsonrpc": "2.0",
            "id": 1,
            "method": "tools/call",
            "params": {
                "name": "get_tax_deductible_summary",
                "arguments": {
                    "startDate": start_date,
                    "endDate": end_date
                }
            }
        }
    )
    
    result = response.json()
    if "result" in result and "content" in result["result"]:
        return result["result"]["content"][0]["json"]["data"]
    return result

# Usage - Get FY tax deductions (Australian financial year: Jul-Jun)
tax_summary = get_tax_deductible_summary("2024-07-01", "2025-06-30")
print(f"Total tax deductible: ${tax_summary['totalAmount']:,.2f}")
print(f"Categories: {len(tax_summary['byCategory'])}")
# Output: Total tax deductible: $12,450.67
#         Categories: 8

TypeScript - Using MCP Protocol

const TOKEN = 'eyJhbGciOiJIUzI1NiIs...';  // JWT token
// OR
const API_KEY = 'mcp_a1b2c3d4e5f6...';  // API key

const BASE_URL = 'https://api.ai2fin.com';

interface TaxDeductionSummary {
  totalCount: number;
  totalAmount: number;
  byCategory: Array<{
    category: string;
    count: number;
    total: number;
    totalGST: number;
  }>;
}

async function getTaxDeductibleSummary(
  startDate: string,
  endDate: string,
  useApiKey: boolean = false
): Promise<TaxDeductionSummary> {
  const endpoint = useApiKey ? '/mcp/inspector' : '/mcp';
  const authHeader = useApiKey ? 'X-API-Key' : 'Authorization';
  const authValue = useApiKey ? API_KEY : `Bearer ${TOKEN}`;
  
  const response = await fetch(`${BASE_URL}${endpoint}`, {
    method: 'POST',
    headers: {
      [authHeader]: authValue,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      jsonrpc: '2.0',
      id: 1,
      method: 'tools/call',
      params: {
        name: 'get_tax_deductible_summary',
        arguments: {
          startDate,
          endDate
        }
      }
    })
  });
  
  const result = await response.json();
  if (result.result?.content?.[0]?.json?.data) {
    return result.result.content[0].json.data;
  }
  throw new Error(result.error?.message || 'Failed to get tax summary');
}

// Usage - Get tax deductions for current financial year
const taxSummary = await getTaxDeductibleSummary('2024-07-01', '2025-06-30');
console.log(`Total tax deductible: $${taxSummary.totalAmount.toLocaleString()}`);
console.log(`Categories: ${taxSummary.byCategory.length}`);

Example 2: Expense Tracking & Spending Analysis

Use Case: Analyze spending patterns and identify top expense categories User Intent: “Where does my money go? What are my biggest expense categories?”

Python - Spending Analysis

import requests
from datetime import datetime, timedelta

TOKEN = "eyJhbGciOiJIUzI1NiIs..."
BASE_URL = "https://api.ai2fin.com"

def get_spending_analysis(month: str):
    """Get comprehensive spending analysis for a month"""
    # Calculate date range
    year, month_num = map(int, month.split('-'))
    start_date = f"{year}-{month_num:02d}-01"
    
    # Get last day of month
    if month_num == 12:
        end_date = f"{year + 1}-01-01"
    else:
        end_date = f"{year}-{month_num + 1:02d}-01"
    
    # Get category spending summary
    response = requests.post(
        f"{BASE_URL}/mcp",
        headers={
            "Authorization": f"Bearer {TOKEN}",
            "Content-Type": "application/json"
        },
        json={
            "jsonrpc": "2.0",
            "id": 1,
            "method": "tools/call",
            "params": {
                "name": "get_category_spending_summary",
                "arguments": {
                    "startDate": start_date,
                    "endDate": end_date
                }
            }
        }
    )
    
    result = response.json()
    return result["result"]["content"][0]["json"]["data"]

# Usage
spending = get_spending_analysis("2024-10")
print(f"Total spending: ${spending['totalSpending']:,.2f}")
print(f"Top category: {spending['topCategory']['name']} - ${spending['topCategory']['total']:,.2f}")
# Output: Total spending: $3,876.43
#         Top category: Groceries - $1,245.67

TypeScript - Top Merchants Analysis

async function getTopMerchants(startDate: string, endDate: string, limit: number = 10) {
  const response = await fetch('https://api.ai2fin.com/mcp', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${TOKEN}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      jsonrpc: '2.0',
      id: 1,
      method: 'tools/call',
      params: {
        name: 'get_top_merchants',
        arguments: {
          startDate,
          endDate,
          limit
        }
      }
    })
  });
  
  const result = await response.json();
  return result.result.content[0].json.data;
}

// Usage - Find where you spend the most
const topMerchants = await getTopMerchants('2024-01-01', '2024-12-31', 10);
console.log('Top 10 Merchants:');
topMerchants.merchants.forEach((m: any, i: number) => {
  console.log(`${i + 1}. ${m.merchant}: $${m.total.toLocaleString()}`);
});

Example 3: Bill Management Automation

Use Case: Automate bill tracking and payment reminders User Intent: “I need to track my recurring bills and get reminders when they’re due”

Python - Bill Payment Automation

def check_overdue_bills():
    """Check for overdue bills and send reminders"""
    response = requests.post(
        f"{BASE_URL}/mcp",
        headers={
            "Authorization": f"Bearer {TOKEN}",
            "Content-Type": "application/json"
        },
        json={
            "jsonrpc": "2.0",
            "id": 1,
            "method": "tools/call",
            "params": {
                "name": "get_overdue_bills",
                "arguments": {}
            }
        }
    )
    
    result = response.json()
    overdue_bills = result["result"]["content"][0]["json"]["data"]["bills"]
    
    if overdue_bills:
        total = sum(bill["amount"] for bill in overdue_bills)
        print(f"⚠️ You have {len(overdue_bills)} overdue bills totaling ${total:,.2f}")
        for bill in overdue_bills:
            print(f"  - {bill['name']}: ${bill['amount']:.2f} (Due: {bill['dueDate']})")
    else:
        print("✅ No overdue bills!")
    
    return overdue_bills

# Usage
overdue = check_overdue_bills()

TypeScript - Bill Payment Workflow

async function markBillAsPaid(billPatternId: string, occurrenceId: string) {
  // First call - get confirmation token
  const preview = await fetch('https://api.ai2fin.com/mcp', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${TOKEN}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      jsonrpc: '2.0',
      id: 1,
      method: 'tools/call',
      params: {
        name: 'mark_bill_as_paid',
        arguments: {
          billPatternId,
          occurrenceId
        }
      }
    })
  });
  
  const previewResult = await preview.json();
  
  if (previewResult.result.content[0].json.needsConfirmation) {
    const confirmToken = previewResult.result.content[0].json.confirmToken;
    
    // Second call - confirm and execute
    const confirm = await fetch('https://api.ai2fin.com/mcp', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${TOKEN}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        jsonrpc: '2.0',
        id: 2,
        method: 'tools/call',
        params: {
          name: 'mark_bill_as_paid',
          arguments: {
            billPatternId,
            occurrenceId,
            confirmToken
          }
        }
      })
    });
    
    return await confirm.json();
  }
  
  return previewResult;
}

Example 4: Receipt Processing Automation

Use Case: Automatically process receipts from email or uploads User Intent: “I need to automatically extract data from receipts and create expenses” Maintain conversation history across multiple requests.

class AI2FinChat {
  private token: string;
  private conversationId: string | null = null;
  
  constructor(token: string) {
    this.token = token;
  }
  
  async chat(message: string): Promise<string> {
    const response = await fetch('https://app.ai2fin.com/api/chat/message', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.token}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        message,
        conversationId: this.conversationId
      })
    });
    
    const data = await response.json();
    
    // Save conversation ID for history
    this.conversationId = data.data.conversationId;
    
    return data.data.message.content;
  }
  
  async getHistory(): Promise<Message[]> {
    if (!this.conversationId) return [];
    
    const response = await fetch(
      `https://app.ai2fin.com/api/chat/conversations/${this.conversationId}`,
      {
        headers: { 'Authorization': `Bearer ${this.token}` }
      }
    );
    
    const data = await response.json();
    return data.data;
  }
}

// Usage
const chat = new AI2FinChat('YOUR_TOKEN');

// First message
await chat.chat("Show my transactions");
// AI: "You have 47 transactions..."

// Second message (AI remembers context!)
await chat.chat("Which ones are tax deductible?");
// AI: "Of those 47, 23 are tax deductible..."

// Get full history
const history = await chat.getHistory();
console.log(history);  // All messages retained

Python - Smart Receipt Processor

def process_receipt(receipt_url: str):
    """One-call receipt processing workflow"""
    response = requests.post(
        f"{BASE_URL}/mcp",
        headers={
            "Authorization": f"Bearer {TOKEN}",
            "Content-Type": "application/json"
        },
        json={
            "jsonrpc": "2.0",
            "id": 1,
            "method": "tools/call",
            "params": {
                "name": "smart_receipt_processor",
                "arguments": {
                    "assetUrl": receipt_url,
                    "mimeType": "image/jpeg",
                    "size": 245123,
                    "autoLinkToBill": True
                }
            }
        }
    )
    
    result = response.json()
    return result["result"]["content"][0]["json"]["data"]

# Usage
receipt_data = process_receipt("https://example.com/receipt.jpg")
print(f"✅ Created transaction: ${receipt_data['transaction']['amount']:.2f}")
print(f"   Merchant: {receipt_data['merchant']}")
# GST is detected and filled in for you automatically

Example 5: ChatGPT Integration

Use Case: Connect ChatGPT to your financial data via OAuth User Intent: “I want ChatGPT to answer questions about my finances” Build a command-line interface for AI2Fin.

#!/usr/bin/env python3
import sys
from ai2fin_mcp import AI2FinChat

def main():
    token = input("Enter your AI2Fin token: ")
    chat = AI2FinChat(token)
    
    print("AI2Fin Assistant (type 'exit' to quit)\n")
    
    while True:
        user_input = input("You: ")
        
        if user_input.lower() == 'exit':
            break
            
        response = chat.send_message(user_input)
        print(f"AI: {response}\n")

if __name__ == "__main__":
    main()

Usage:

$ python ai2fin_cli.py
Enter your AI2Fin token: eyJhbGciOiJIUzI1NiIs...
AI2Fin Assistant (type 'exit' to quit)

You: Show my bills
AI: You have 12 recurring bills totaling $445.50 monthly...

You: What's due this week?
AI: You have 3 bills due this week:
- Netflix ($15.99) - Due Nov 5
- Spotify ($11.99) - Due Nov 8
- Adobe CC ($54.99) - Due Nov 10

You: exit

OAuth Configuration

{
  "name": "AI2Fin Finance Assistant",
  "description": "Connect your AI assistant to your AI2Fin financial data",
  "authentication": {
    "type": "oauth",
    "authorization_url": "https://api.ai2fin.com/api/auth/oauth/authorize",
    "token_url": "https://api.ai2fin.com/api/auth/oauth/token",
    "scopes": ["read:financial_data", "write:transactions"]
  },
  "mcp_endpoint": "https://api.ai2fin.com/mcp"
}

User Experience:

User connects AI assistant to AI2Fin via OAuth
AI assistant can now answer: “What are my tax deductible expenses?”
AI assistant calls get_tax_deductible_summary via MCP
Returns formatted financial insights

Example 6: Custom Financial AI Agent

Use Case: Build a custom financial AI assistant User Intent: “I want a custom AI agent that understands my business finances”

const { App } = require('@slack/bolt');
const { AI2FinMCP } = require('ai2fin-mcp-sdk');

const app = new App({
  token: process.env.SLACK_BOT_TOKEN,
  signingSecret: process.env.SLACK_SIGNING_SECRET
});

// Map Slack users to AI2Fin tokens (securely!)
const userTokens = new Map();

app.message(async ({ message, say }) => {
  const userId = message.user;
  const ai2finToken = userTokens.get(userId);
  
  if (!ai2finToken) {
    await say("Please authenticate with AI2Fin first: /ai2fin-login");
    return;
  }
  
  // Send to AI2Fin MCP
  const mcp = new AI2FinMCP(ai2finToken);
  const response = await mcp.chat(message.text);
  
  await say(response.data.message.content);
});

app.start(3000);

Result: Ask AI2Fin questions directly in Slack! ✅

Python - Custom Financial Agent

import requests
from typing import Dict, Any

class FinancialAIAgent:
    def __init__(self, api_key: str):
        self.api_key = api_key
        self.base_url = "https://api.ai2fin.com"
    
    def call_mcp_tool(self, tool_name: str, arguments: Dict[str, Any]):
        """Call any MCP financial tool"""
        response = requests.post(
            f"{self.base_url}/mcp/inspector",
            headers={
                "X-API-Key": self.api_key,
                "Content-Type": "application/json"
            },
            json={
                "jsonrpc": "2.0",
                "id": 1,
                "method": "tools/call",
                "params": {
                    "name": tool_name,
                    "arguments": arguments
                }
            }
        )
        return response.json()
    
    def get_financial_summary(self, period: str = "this_month"):
        """Get comprehensive financial summary"""
        # Get spending by category
        spending = self.call_mcp_tool("get_category_spending_summary", {
            "startDate": "2024-01-01",
            "endDate": "2024-12-31"
        })
        
        # Get tax deductions
        tax = self.call_mcp_tool("get_tax_deductible_summary", {
            "startDate": "2024-07-01",
            "endDate": "2025-06-30"
        })
        
        # Get upcoming bills
        bills = self.call_mcp_tool("get_upcoming_bills", {
            "daysAhead": 30
        })
        
        return {
            "spending": spending["result"]["content"][0]["json"]["data"],
            "tax_deductions": tax["result"]["content"][0]["json"]["data"],
            "upcoming_bills": bills["result"]["content"][0]["json"]["data"]
        }

# Usage
agent = FinancialAIAgent("mcp_a1b2c3d4e5f6...")
summary = agent.get_financial_summary()
print(f"Total spending: ${summary['spending']['totalSpending']:,.2f}")
print(f"Tax deductible: ${summary['tax_deductions']['totalAmount']:,.2f}")

Example 7: Error Handling & Retry Logic

async function safeMCPCall(message: string, token: string) {
  try {
    const response = await fetch('https://app.ai2fin.com/api/chat/message', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ message })
    });
    
    const data = await response.json();
    
    if (!data.success) {
      // Handle MCP errors
      if (response.status === 401) {
        return "Authentication failed. Please login again.";
      } else if (response.status === 429) {
        return "Rate limit exceeded. Please wait a minute.";
      } else {
        return `Error: ${data.error}`;
      }
    }
    
    return data.data.message.content;
    
  } catch (error) {
    return `Network error: ${error.message}`;
  }
}

TypeScript - Robust Error Handling

async function callMCPWithRetry(
  toolName: string,
  arguments: any,
  maxRetries: number = 3
): Promise<any> {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch('https://api.ai2fin.com/mcp', {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${TOKEN}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          jsonrpc: '2.0',
          id: Date.now(),
          method: 'tools/call',
          params: {
            name: toolName,
            arguments
          }
        })
      });
      
      const result = await response.json();
      
      // Handle rate limiting with exponential backoff
      if (response.status === 429) {
        // Use the documented X-RateLimit-Reset header (epoch seconds) to
        // wait until the limit resets; otherwise fall back to backoff.
        const resetAt = response.headers.get('X-RateLimit-Reset');
        const waitTime = resetAt
          ? Math.max(0, parseInt(resetAt) * 1000 - Date.now())
          : Math.pow(2, attempt) * 1000;

        if (attempt < maxRetries - 1) {
          await new Promise(resolve => setTimeout(resolve, waitTime));
          continue;
        }
      }
      
      // Handle errors
      if (result.error) {
        throw new Error(result.error.message || 'MCP error');
      }
      
      return result.result.content[0].json.data;
      
    } catch (error: any) {
      if (attempt === maxRetries - 1) {
        throw error;
      }
      
      // Exponential backoff
      await new Promise(resolve => 
        setTimeout(resolve, Math.pow(2, attempt) * 1000)
      );
    }
  }
}

Example 8: Multi-User Enterprise Application

// Enterprise app with multiple AI2Fin users
class EnterpriseAI2FinService {
  private userSessions = new Map<string, { token: string, conversationId: string }>();
  
  async handleUserQuery(userId: string, query: string): Promise<string> {
    // Get user's AI2Fin session
    const session = this.userSessions.get(userId);
    
    if (!session) {
      throw new Error('User not authenticated with AI2Fin');
    }
    
    // Call MCP with user's token (isolated!)
    const response = await fetch('https://app.ai2fin.com/api/chat/message', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${session.token}`,  // User-specific!
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        message: query,
        conversationId: session.conversationId
      })
    });
    
    const data = await response.json();
    
    // Update conversation ID
    session.conversationId = data.data.conversationId;
    
    return data.data.message.content;
  }
}

// Each user gets isolated access ✅

TypeScript - Enterprise Multi-User Service

class EnterpriseFinancialService {
  private userSessions = new Map<string, { 
    token: string; 
    apiKey?: string;
    conversationId?: string;
  }>();
  
  async handleUserQuery(
    userId: string, 
    query: string,
    useApiKey: boolean = false
  ): Promise<string> {
    const session = this.userSessions.get(userId);
    
    if (!session) {
      throw new Error('User not authenticated with AI2Fin');
    }
    
    const endpoint = useApiKey ? '/mcp/inspector' : '/mcp';
    const authHeader = useApiKey ? 'X-API-Key' : 'Authorization';
    const authValue = useApiKey 
      ? session.apiKey! 
      : `Bearer ${session.token}`;
    
    const response = await fetch(`https://api.ai2fin.com${endpoint}`, {
      method: 'POST',
      headers: {
        [authHeader]: authValue,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        jsonrpc: '2.0',
        id: Date.now(),
        method: 'tools/call',
        params: {
          name: this.determineTool(query),
          arguments: this.extractArguments(query)
        }
      })
    });
    
    const result = await response.json();
    return result.result.content[0].json.data;
  }
  
  private determineTool(query: string): string {
    // Simple intent detection
    if (query.includes('tax') || query.includes('deductible')) {
      return 'get_tax_deductible_summary';
    }
    if (query.includes('spending') || query.includes('category')) {
      return 'get_category_spending_summary';
    }
    if (query.includes('bill')) {
      return 'get_upcoming_bills';
    }
    return 'get_transactions';
  }
  
  private extractArguments(query: string): any {
    // Extract date ranges, filters, etc. from query
    return {
      startDate: '2024-01-01',
      endDate: '2024-12-31'
    };
  }
}

// Each user gets isolated access ✅

Example 9: Automated Financial Reporting

import speech_recognition as sr
from ai2fin_mcp import AI2FinChat
import pyttsx3

# Initialize
recognizer = sr.Recognizer()
tts = pyttsx3.init()
chat = AI2FinChat(token="YOUR_TOKEN")

def voice_assistant():
    with sr.Microphone() as source:
        print("Listening...")
        audio = recognizer.listen(source)
        
    try:
        # Speech to text
        text = recognizer.recognize_google(audio)
        print(f"You: {text}")
        
        # Send to AI2Fin
        response = chat.send_message(text)
        print(f"AI: {response}")
        
        # Text to speech
        tts.say(response)
        tts.runAndWait()
        
    except Exception as e:
        print(f"Error: {e}")

# Usage
while True:
    voice_assistant()

Python - Weekly Financial Report Automation

from datetime import datetime, timedelta
import smtplib
from email.mime.text import MIMEText

def generate_weekly_report():
    """Generate and email weekly financial report"""
    # Get date range for last week
    end_date = datetime.now()
    start_date = end_date - timedelta(days=7)
    
    # Get spending summary
    spending = call_mcp_tool("get_category_spending_summary", {
        "startDate": start_date.strftime("%Y-%m-%d"),
        "endDate": end_date.strftime("%Y-%m-%d")
    })
    
    # Get top merchants
    merchants = call_mcp_tool("get_top_merchants", {
        "startDate": start_date.strftime("%Y-%m-%d"),
        "endDate": end_date.strftime("%Y-%m-%d"),
        "limit": 5
    })
    
    # Generate report
    report = f"""
    Weekly Financial Report ({start_date.strftime('%Y-%m-%d')} to {end_date.strftime('%Y-%m-%d')})
    
    Total Spending: ${spending['totalSpending']:,.2f}
    
    Top Categories:
    {chr(10).join([f"  • {cat['name']}: ${cat['total']:,.2f}" for cat in spending['categories'][:5]])}
    
    Top Merchants:
    {chr(10).join([f"  • {m['merchant']}: ${m['total']:,.2f}" for m in merchants['merchants']])}
    """
    
    # Send email (implement email sending logic)
    send_email_report(report)
    return report

Example 10: Receipt Email Automation

NEW - Using Analytics Tools

Build a spending analytics dashboard using the new tools.

async function getSpendingInsights(token: string, month: string) {
  const baseUrl = 'https://app.ai2fin.com';
  const headers = {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  };
  
  // Calculate date range
  const startDate = `${month}-01`;
  const endDate = new Date(new Date(month).getFullYear(), new Date(month).getMonth() + 1, 0)
    .toISOString().split('T')[0];
  
  // Use AI chat to get insights
  const response = await fetch(`${baseUrl}/api/chat/message`, {
    method: 'POST',
    headers,
    body: JSON.stringify({
      message: `Give me a complete spending analysis for ${month} including:
        1. Breakdown by category
        2. Top 5 merchants
        3. Comparison vs previous month`
    })
  });
  
  const data = await response.json();
  return data.data.message.content;
}

// Usage
const insights = await getSpendingInsights('YOUR_TOKEN', '2024-10');
console.log(insights);

/*
Output:
"October 2024 Spending Analysis:

📊 By Category:
• Groceries: $1,245.67 (32%)
• Dining Out: $876.43 (23%)
• Transport: $654.32 (17%)

🏪 Top Merchants:
1. Woolworths - $487.23
2. Caltex - $312.45
3. Uber - $234.67

📈 vs September:
Total: $3,876 vs $3,234 (+19.9% increase)
Biggest increase: Dining Out (+36.5%)"
*/

Python - Process Receipts from Email

import imaplib
import email
from email.header import decode_header

def process_receipt_emails():
    """Monitor email for receipts and process automatically"""
    # Connect to email (example with Gmail)
    mail = imaplib.IMAP4_SSL("imap.gmail.com")
    mail.login("[email protected]", "app_password")
    mail.select("inbox")
    
    # Search for receipt emails
    _, messages = mail.search(None, 'SUBJECT "receipt" OR SUBJECT "invoice"')
    
    for msg_num in messages[0].split():
        _, msg_data = mail.fetch(msg_num, "(RFC822)")
        email_body = msg_data[0][1]
        email_message = email.message_from_bytes(email_body)
        
        # Extract attachments
        for part in email_message.walk():
            if part.get_content_type() == "image/jpeg" or part.get_content_type() == "application/pdf":
                filename = part.get_filename()
                if filename:
                    # Download attachment
                    attachment_path = download_attachment(part, filename)
                    
                    # Upload to AI2Fin
                    upload_url = upload_to_ai2fin(attachment_path)
                    
                    # Process receipt via MCP
                    receipt_data = call_mcp_tool("smart_receipt_processor", {
                        "assetUrl": upload_url,
                        "mimeType": "image/jpeg",
                        "size": 245123
                    })
                    
                    print(f"✅ Processed receipt: {receipt_data['merchant']} - ${receipt_data['total']:.2f}")

Example 11: Tax Season Preparation

NEW - Batch Processing

Efficiently categorize large numbers of transactions.

async function bulkCategorizeByMerchant(
  token: string,
  merchant: string,
  categoryId: string
) {
  const response = await fetch('https://app.ai2fin.com/api/chat/message', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      message: `Categorize all ${merchant} transactions as ${categoryId}`
    })
  });
  
  const data = await response.json();
  return data.data.message.content;
}

// Usage
await bulkCategorizeByMerchant(
  'YOUR_TOKEN',
  'Uber',
  'cat_transport_123'
);
// Output: "✅ Updated 15 transaction(s) to category "Transport""

Python - Comprehensive Tax Report

def generate_tax_report(financial_year: str = "2024-2025"):
    """Generate comprehensive tax report for financial year"""
    # Determine FY dates based on country (AU: Jul-Jun, US: Oct-Sep, etc.)
    fy_start, fy_end = get_fy_dates(financial_year, country_code="AU")
    
    # Get tax deductible summary
    tax_summary = call_mcp_tool("get_tax_deductible_summary", {
        "startDate": fy_start,
        "endDate": fy_end
    })
    
    # Get bill financial summaries
    bills = call_mcp_tool("get_bills", {})
    bill_summaries = []
    for bill in bills["bills"]:
        bill_fy = call_mcp_tool("get_bill_pattern_financial_summary", {
            "billPatternId": bill["id"],
            "period": "this_fy"
        })
        bill_summaries.append(bill_fy)
    
    # Get travel deductions
    travel = call_mcp_tool("get_travel_deduction_summary", {
        "startDate": fy_start,
        "endDate": fy_end
    })
    
    # Compile report
    report = {
        "financial_year": financial_year,
        "tax_deductible_expenses": tax_summary,
        "recurring_bills": bill_summaries,
        "travel_deductions": travel,
        "total_deductions": (
            tax_summary["totalAmount"] + 
            travel["totalDeduction"]
        )
    }
    
    return report

# Usage
tax_report = generate_tax_report("2024-2025")
print(f"Total tax deductions: ${tax_report['total_deductions']:,.2f}")

Example 12: Duplicate Transaction Detection

NEW - Find Double Charges

Detect and alert users about potential duplicate payments.

from ai2fin_mcp import AI2FinChat
from datetime import datetime, timedelta

def check_duplicates(token: str):
    """Check last 30 days for duplicates"""
    chat = AI2FinChat(token)
    
    end_date = datetime.now()
    start_date = end_date - timedelta(days=30)
    
    message = f"Find duplicate transactions from {start_date.date()} to {end_date.date()}"
    response = chat.send_message(message)
    
    return response

# Usage
result = check_duplicates('YOUR_TOKEN')
print(result)

# Output:
# "🔍 Found 2 potential duplicate groups:
# 
# 1. Netflix - $15.99
#    • Oct 15 at 3:45 PM
#    • Oct 15 at 11:23 PM
# 
# 2. Woolworths - $87.45
#    • Oct 12 at 9:15 AM
#    • Oct 12 at 9:17 AM (2 min apart)
# 
# Potential savings if duplicates: $103.44"

TypeScript - Find Duplicate Payments

async function findDuplicateTransactions(
  startDate: string,
  endDate: string
) {
  const response = await fetch('https://api.ai2fin.com/mcp', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${TOKEN}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      jsonrpc: '2.0',
      id: 1,
      method: 'tools/call',
      params: {
        name: 'find_duplicate_transactions',
        arguments: {
          startDate,
          endDate
        }
      }
    })
  });
  
  const result = await response.json();
  const duplicates = result.result.content[0].json.data.duplicates;
  
  if (duplicates.length > 0) {
    console.log(`⚠️ Found ${duplicates.length} potential duplicate groups`);
    duplicates.forEach((group: any) => {
      console.log(`  ${group.merchant} - $${group.amount}: ${group.count} transactions`);
    });
  }
  
  return duplicates;
}

// Usage
const duplicates = await findDuplicateTransactions('2024-01-01', '2024-12-31');

Example 13: Financial Year Analysis

NEW - Country-Aware FY Queries

Get financial year summaries for any bill pattern.

async function getFYSummary(
  token: string,
  merchantName: string,
  includeProjections: boolean = true
) {
  const response = await fetch('https://app.ai2fin.com/api/chat/message', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      message: `How much have I paid for ${merchantName} this financial year?${includeProjections ? ' Include projections.' : ''}`
    })
  });
  
  const data = await response.json();
  return data.data.message.content;
}

// Usage (Australian user)
const netflixFY = await getFYSummary('YOUR_TOKEN', 'Netflix', true);
console.log(netflixFY);

/*
Output:
"Netflix - Financial Year 2024-2025 (AU: Jul-Jun)

✅ Paid to Date (Jul-Nov):
• 5 payments × $15.99 = $79.95

📊 Projected (Dec-Jun):
• 7 payments × $15.99 = $111.93

💰 Full FY Estimate: $191.88
(Actual: $79.95 + Projected: $111.93)"
*/

Common Integration Patterns

Pattern 1: Tax Deduction Workflow

User Intent: “I need to maximize my tax deductions”

# 1. Get tax deductible summary
tax_summary = call_mcp_tool("get_tax_deductible_summary", {...})

# 2. Find opportunities
opportunities = call_mcp_tool("suggest_tax_deductions", {...})

# 3. Analyze specific transactions
for transaction_id in opportunities["transactionIds"]:
    analysis = call_mcp_tool("analyze_transaction_tax_deductibility", {
        "transactionId": transaction_id
    })
    
# 4. Apply recommendations
if user_confirms:
    call_mcp_tool("apply_analysis_to_transaction", {...})

Pattern 2: Spending Optimization

User Intent: “How can I reduce my expenses?”

# 1. Get spending breakdown
spending = call_mcp_tool("get_category_spending_summary", {...})

# 2. Compare periods
comparison = call_mcp_tool("compare_spending_periods", {
    "period1Start": "2024-01-01",
    "period1End": "2024-03-31",
    "period2Start": "2024-04-01",
    "period2End": "2024-06-30"
})

# 3. Get top merchants
merchants = call_mcp_tool("get_top_merchants", {...})

# 4. Generate recommendations
recommendations = call_mcp_tool("suggest_budgets", {...})

Pattern 3: Bill Payment Automation

User Intent: “I want to automate bill payments”

# 1. Get overdue bills
overdue = call_mcp_tool("get_overdue_bills", {})

# 2. Get upcoming bills
upcoming = call_mcp_tool("get_upcoming_bills", {"daysAhead": 7})

# 3. Mark bills as paid (with confirmation)
for bill in overdue["bills"]:
    # First call - get confirmation
    preview = call_mcp_tool("mark_bill_as_paid", {
        "billPatternId": bill["id"],
        "occurrenceId": bill["occurrenceId"]
    })
    
    if preview["needsConfirmation"]:
        # Second call - confirm
        result = call_mcp_tool("mark_bill_as_paid", {
            "billPatternId": bill["id"],
            "occurrenceId": bill["occurrenceId"],
            "confirmToken": preview["confirmToken"]
        })

Frequently Asked Questions

How do I integrate MCP with my financial data?

Connect your AI assistant to the AI2Fin Finance MCP server using either an API key (best for automation) or an OAuth access token (best for user-specific integrations). Once connected, your assistant can call finance tools like get_tax_deductible_summary, get_category_spending_summary, and get_upcoming_bills to answer questions in natural language. The Python and TypeScript examples above show the exact request format.

Can I connect ChatGPT or Claude to my AI2Fin data?

Yes. The AI2Fin Finance MCP server works with any MCP-compatible assistant, including ChatGPT, Claude, and Cursor. See Example 5: ChatGPT Integration for the OAuth setup, and the Cursor integration guide for a step-by-step walkthrough.

Which programming languages are supported?

The MCP server speaks the standard JSON-RPC MCP protocol over HTTPS, so you can call it from any language that can make HTTP requests. The examples here use Python and TypeScript, but the same request format works in Go, Ruby, C#, and more.

What can the finance tools actually do?

You can analyse tax deductions, break spending down by category and merchant, compare time periods, track recurring bills, detect duplicate payments, and generate financial-year summaries. See the Transaction Tools, Bill Tools, and Subscription Tools references for the full list.

SDK Libraries

Official SDKs (Coming Soon)

# Python
pip install ai2fin-mcp-sdk

# JavaScript/TypeScript
npm install @ai2fin/mcp-sdk

# Go
go get github.com/ai2fin/mcp-sdk-go

Community SDKs

Check our GitHub for community-contributed SDKs.

Next Steps

Quickstart Guide

Get started in 5 minutes

Tools Reference

Explore all 34 financial tools

Authentication

OAuth and API key setup

API Reference

Complete API documentation

​Quick Navigation

Tax & Deductions

Expense Tracking

Bill Management

Receipt Processing

ChatGPT Integration

Custom AI Agents

​Example 1: Tax Deduction Analysis

​Python - Using MCP Protocol

​TypeScript - Using MCP Protocol

​Example 2: Expense Tracking & Spending Analysis

​Python - Spending Analysis

​TypeScript - Top Merchants Analysis

​Example 3: Bill Management Automation

​Python - Bill Payment Automation

​TypeScript - Bill Payment Workflow

​Example 4: Receipt Processing Automation

​Python - Smart Receipt Processor

​Example 5: ChatGPT Integration

​OAuth Configuration

​Example 6: Custom Financial AI Agent

​Python - Custom Financial Agent

​Example 7: Error Handling & Retry Logic

​TypeScript - Robust Error Handling

​Example 8: Multi-User Enterprise Application

​TypeScript - Enterprise Multi-User Service

​Example 9: Automated Financial Reporting

​Python - Weekly Financial Report Automation

​Example 10: Receipt Email Automation

​Python - Process Receipts from Email

​Example 11: Tax Season Preparation

​Python - Comprehensive Tax Report

​Example 12: Duplicate Transaction Detection

​TypeScript - Find Duplicate Payments

​Example 13: Financial Year Analysis

​Common Integration Patterns

​Pattern 1: Tax Deduction Workflow

​Pattern 2: Spending Optimization

​Pattern 3: Bill Payment Automation

​Frequently Asked Questions

​SDK Libraries

​Official SDKs (Coming Soon)

​Community SDKs

​Next Steps

Quickstart Guide

Tools Reference

Authentication

API Reference

Quick Navigation

Example 1: Tax Deduction Analysis

Python - Using MCP Protocol

TypeScript - Using MCP Protocol

Example 2: Expense Tracking & Spending Analysis

Python - Spending Analysis

TypeScript - Top Merchants Analysis

Example 3: Bill Management Automation

Python - Bill Payment Automation

TypeScript - Bill Payment Workflow

Example 4: Receipt Processing Automation

Python - Smart Receipt Processor

Example 5: ChatGPT Integration

OAuth Configuration

Example 6: Custom Financial AI Agent

Python - Custom Financial Agent

Example 7: Error Handling & Retry Logic

TypeScript - Robust Error Handling

Example 8: Multi-User Enterprise Application

TypeScript - Enterprise Multi-User Service

Example 9: Automated Financial Reporting

Python - Weekly Financial Report Automation

Example 10: Receipt Email Automation

Python - Process Receipts from Email

Example 11: Tax Season Preparation

Python - Comprehensive Tax Report

Example 12: Duplicate Transaction Detection

TypeScript - Find Duplicate Payments

Example 13: Financial Year Analysis

Common Integration Patterns

Pattern 1: Tax Deduction Workflow

Pattern 2: Spending Optimization

Pattern 3: Bill Payment Automation

Frequently Asked Questions

SDK Libraries

Official SDKs (Coming Soon)

Community SDKs

Next Steps