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

• Features
• Quick Start
• Prerequisites
• Installation
• Configuration
• Usage
• API Reference
• Testing
• Deployment
• Contributing
• Troubleshooting
• Security
• License

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

1. Create Xero App

   • Go to Xero Developer Portal
   • Click "New App" and select "Web app"
   • Enter your app details

2. Configure OAuth 2.0

   • Set redirect URI to: http://localhost:3000/api/auth/callback
   • Copy Client ID and Client Secret to your .env.local

3. 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

1. Connect Repository

   # Vercel will automatically detect Next.js
   vercel --prod
   

2. Environment Variables

   • Add all environment variables in Vercel dashboard
   • Enable "Fluid Compute" for better performance
   • Set function timeout to 30 seconds for MCP operations

3. 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

1. Fork & Clone

   git clone https://github.com/your-username/xero-mcp-with-next-js.git
   cd xero-mcp-with-next-js
   

2. Install Dependencies

   npm install
   

3. Run Tests

   npm test
   

4. 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

1. Create a feature branch: git checkout -b feature/amazing-feature
2. Write tests for your changes
3. Ensure all tests pass: npm test
4. Update documentation if needed
5. 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)

• [x] Basic MCP tool implementation
• [x] OAuth 2.0 integration
• [x] Webhook support
• [x] Comprehensive testing suite
• [x] 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, Bookkeepers and AI enthusiasts

⭐ Star us on GitHub • [📖 Documentation](Still to do) • 🐛 Report Issues