Skip to main content
Glama

Next.js MCP Server Template

by hiltonbrown
GitHub
TypeScript
MIT License
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

Xero MCP Integration Server

Build Status License: MIT Node.js Version TypeScript Next.js

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

Deploy with Vercel

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

  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

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

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

A template for building MCP servers in Next.js applications using the Vercel MCP Adapter. Provides a foundation for adding custom tools, prompts, and resources to any Next.js project with deployment support on Vercel.

  1. Features
    1. What You Can Do
      1. Quick Start
        1. 1. Clone & Install
        2. 2. Configure Environment
        3. 3. Start Development Server
      2. 📋 Table of Contents
        1. Prerequisites
          1. Installation
            1. Option 1: Local Development (Recommended)
            2. Option 2: Using Docker
            3. Option 3: Vercel One-Click Deploy
          2. Configuration
            1. Environment Variables
            2. Xero Developer Setup
            3. Database Setup
          3. Usage
            1. Connecting AI Assistants
            2. Example Queries
            3. API Endpoints
          4. 📚 API Reference
            1. MCP Tools Available
            2. Response Format
          5. Testing
            1. Test Coverage
          6. Deployment
            1. Vercel Deployment
            2. Docker Deployment
            3. Production Checklist
          7. Contributing
            1. Development Setup
            2. Code Standards
            3. Pull Request Process
            4. Commit Message Format
          8. Troubleshooting
            1. Common Issues
            2. Debug Mode
            3. Getting Help
          9. Security
            1. Data Protection
            2. Best Practices
            3. Security Reporting
          10. Roadmap
            1. Version 2.0 (Coming Soon)
            2. Version 1.5 (Current)
          11. Acknowledgments
            1. License

              New MCP Servers

              MCP directory API

              We provide all the information about MCP servers via our MCP API.

              curl -X GET 'https://glama.ai/api/mcp/v1/servers/hiltonbrown/xero-mcp-with-next-js'

              If you have feedback or need assistance with the MCP directory API, please join our Discord server