Next.js MCP Server Template

Xero MCP Integration Server 🚀

Connect AI assistants to Xero accounting data seamlessly

Transform your Xero workflow with AI-powered insights and automation. This server enables AI assistants like Claude, ChatGPT, or any Model Context Protocol (MCP) compatible AI to securely access and analyze your Xero accounting data.

✨ Features

🔐 Secure OAuth 2.0 Integration - Enterprise-grade authentication with Xero
🤖 AI Assistant Compatible - Works with Claude, ChatGPT, and other MCP clients
⚡ Real-time Data Access - Live synchronization with Xero accounting data
🛡️ Enterprise Security - Encrypted tokens, CSRF protection, and audit logging
📊 Comprehensive API Coverage - Invoices, contacts, accounts, payments, and more
🚀 Production Ready - Optimized for Vercel deployment with monitoring

🎯 What You Can Do

✅ Instant Financial Insights - Ask "What's my cash flow trend this quarter?" ✅ Automated Reporting - Generate reports with natural language requests ✅ Smart Data Entry - AI-assisted invoice and transaction management ✅ Real-time Alerts - Get notified about important financial events ✅ Multi-tenant Support - Connect multiple Xero organizations

🚀 Quick Start

Get up and running in 3 minutes:

1. Clone & Install

git clone https://github.com/hiltonbrown/xero-mcp-with-next-js.git
cd xero-mcp-with-next-js
npm install

2. Configure Environment

cp .env.example .env.local
# Edit .env.local with your Xero credentials (see Configuration section)

3. Start Development Server

npm run dev

Visit http://localhost:3000 and follow the OAuth flow to connect your Xero account!

📋 Table of Contents

📋 Prerequisites

Before you begin, ensure you have:

Node.js 18+ - Download here
Xero Developer Account - Sign up
PostgreSQL Database - Local or cloud (Supabase, Railway, etc.)
Vercel Account (optional) - For deployment

🛠️ Installation

Option 1: Local Development (Recommended)

# Clone the repository
git clone https://github.com/hiltonbrown/xero-mcp-with-next-js.git
cd xero-mcp-with-next-js

# Install dependencies
npm install

# Set up environment variables
cp .env.example .env.local

# Generate Prisma client
npx prisma generate

# Start development server
npm run dev

Option 2: Using Docker

# Clone and start with Docker
git clone https://github.com/hiltonbrown/xero-mcp-with-next-js.git
cd xero-mcp-with-next-js

# Start all services
docker-compose up -d

# Run database migrations
docker-compose exec app npx prisma migrate deploy

Option 3: Vercel One-Click Deploy

⚙️ Configuration

Environment Variables

Create a .env.local file in the project root:

# Database Configuration
DATABASE_URL="postgresql://username:password@localhost:5432/xero_mcp"

# Xero API Configuration
XERO_CLIENT_ID="your-xero-client-id"
XERO_CLIENT_SECRET="your-xero-client-secret"
XERO_REDIRECT_URI="http://localhost:3000/api/auth/callback"

# Security Configuration
JWT_SECRET="your-256-bit-secret-here"
ENCRYPTION_KEY="your-32-character-encryption-key"

# Optional: Redis for production caching
REDIS_URL="redis://localhost:6379"

# Optional: Monitoring and logging
SENTRY_DSN="your-sentry-dsn-here"

Xero Developer Setup

Create Xero App
- Go to Xero Developer Portal
- Click "New App" and select "Web app"
- Enter your app details
Configure OAuth 2.0
- Set redirect URI to: http://localhost:3000/api/auth/callback
- Copy Client ID and Client Secret to your .env.local
Set Permissions
- Enable required scopes: accounting.transactions, accounting.contacts, etc.

Database Setup

# Install PostgreSQL locally or use a cloud provider
# Then run migrations:
npx prisma migrate deploy

# Optional: Seed with test data
npx prisma db seed

💡 Usage

Connecting AI Assistants

Claude Desktop Integration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "xero": {
      "command": "node",
      "args": ["path/to/your/mcp/server"],
      "env": {
        "XERO_CLIENT_ID": "your-client-id",
        "DATABASE_URL": "your-database-url"
      }
    }
  }
}

ChatGPT Integration

Configure the MCP server URL in your ChatGPT settings:

// Example MCP client connection
const mcpClient = await connectToMCPServer({
  url: 'http://localhost:3000/api/mcp',
  sessionId: 'your-session-id'
});

Example Queries

Once connected, you can ask your AI assistant:

"Show me my outstanding invoices over $500"
"What's my total revenue for Q1 2024?"
"List all customers who haven't paid in 30 days"
"Create a summary of my cash flow this month"
"Find transactions with 'Office Supplies' in the description"

API Endpoints

Authentication

# Initiate OAuth flow
GET /api/auth/xero?accountId=123

# OAuth callback handler
GET /api/auth/callback?code=...&state=...

MCP Server

# MCP protocol endpoint
POST /api/mcp
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

Health & Monitoring

# Health check
GET /api/health

# Detailed health check
POST /api/health

Webhooks

# Xero webhook receiver
POST /api/webhooks/xero
X-Xero-Signature: <signature>

📚 API Reference

MCP Tools Available

Tool	Description	Parameters
`list-accounts`	Chart of accounts	`tenantId`, `where`, `orderBy`
`list-contacts`	Customer/supplier contacts	`tenantId`, `where`, `page`, `pageSize`
`list-invoices`	Sales invoices	`tenantId`, `status`, `dateFrom`, `dateTo`
`list-items`	Inventory items	`tenantId`, `where`
`list-payments`	Payment records	`tenantId`, `status`, `dateFrom`, `dateTo`
`create-contact`	New contact	`tenantId`, `name`, `email`, `contactType`
`create-invoice`	New invoice	`tenantId`, `contactId`, `date`, `lineItems`
`update-contact`	Update contact	`tenantId`, `contactId`, `name`, `email`

Response Format

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Found 5 accounts"
      },
      {
        "type": "json",
        "json": [...]
      }
    ]
  }
}

🧪 Testing

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run specific test types
npm run test:unit      # Unit tests
npm run test:api       # API tests
npm run test:integration # Integration tests

# Run tests in watch mode
npm run test:watch

Test Coverage

Unit Tests: Core functions and utilities
API Tests: HTTP endpoints and responses
Integration Tests: End-to-end OAuth and MCP flows
Component Tests: React component testing

🚀 Deployment

Vercel Deployment

Connect Repository
# Vercel will automatically detect Next.js vercel --prod
Environment Variables
- Add all environment variables in Vercel dashboard
- Enable "Fluid Compute" for better performance
- Set function timeout to 30 seconds for MCP operations
Database
- Use Vercel Postgres or connect external PostgreSQL
- Run migrations: npx prisma migrate deploy

Docker Deployment

# Build and run
docker build -t xero-mcp .
docker run -p 3000:3000 xero-mcp

Production Checklist

Environment variables configured
Database migrations run
SSL certificates enabled
Monitoring and alerting set up
Backup procedures documented
Load testing completed

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

Fork & Clone
git clone https://github.com/your-username/xero-mcp-with-next-js.git cd xero-mcp-with-next-js
Install Dependencies
npm install
Run Tests
npm test
Start Development
npm run dev

Code Standards

TypeScript: Strict type checking enabled
ESLint: Code linting with Next.js rules
Prettier: Automated code formatting
Testing: Minimum 80% code coverage required

Pull Request Process

Create a feature branch: git checkout -b feature/amazing-feature
Write tests for your changes
Ensure all tests pass: npm test
Update documentation if needed
Submit a pull request with a clear description

Commit Message Format

feat: add new MCP tool for bank reconciliation
fix: resolve OAuth token refresh issue
docs: update API documentation
test: add integration tests for webhook handling
refactor: improve error handling in auth module

🔧 Troubleshooting

Common Issues

OAuth Connection Failed

# Check Xero app configuration
# Verify redirect URI matches: http://localhost:3000/api/auth/callback
# Ensure Xero app has correct scopes enabled

Database Connection Error

# Verify DATABASE_URL is correct
# Check PostgreSQL is running
# Run: npx prisma migrate deploy

MCP Tool Not Working

# Check session is valid
# Verify Xero connection is active
# Check API permissions in Xero

Build Errors

# Clear Next.js cache
rm -rf .next

# Reinstall dependencies
rm -rf node_modules package-lock.json
npm install

Debug Mode

# Enable debug logging
DEBUG=* npm run dev

# Check health endpoint
curl http://localhost:3000/api/health

Getting Help

📖 Documentation: Full API Docs
💬 Discussions: GitHub Discussions
🐛 Issues: GitHub Issues
📧 Email: support@example.com

🔒 Security

Data Protection

Encrypted Tokens: All sensitive data encrypted with AES-256
Secure Sessions: JWT-based authentication with expiration
CSRF Protection: OAuth state parameter validation
Input Validation: Comprehensive request sanitization

Best Practices

Environment Variables: Never commit secrets to version control
HTTPS Only: Always use HTTPS in production
Regular Updates: Keep dependencies updated for security patches
Access Control: Implement proper authorization checks

Security Reporting

If you discover a security vulnerability, please email security@example.com instead of creating a public issue.

📊 Roadmap

Version 2.0 (Coming Soon)

Advanced reporting tools
Bulk operations support
Real-time webhook notifications
Multi-organization support
Advanced analytics dashboard

Version 1.5 (Current)

Basic MCP tool implementation
OAuth 2.0 integration
Webhook support
Comprehensive testing suite
Production deployment ready

🙏 Acknowledgments

Xero API - For providing excellent accounting APIs
Model Context Protocol - For the AI assistant integration standard
Next.js Community - For the amazing React framework
Vercel - For the best deployment platform

📄 License

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

Made with ❤️ for accountants and AI enthusiasts

⭐ Star us on GitHub • 📖 Documentation • 🐛 Report Issues