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

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)

• 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, Bookkeepers and AI enthusiasts

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