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

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