Xero MCP Server

Xero MCP Sunucusu

Bu, Xero için bir Model Bağlam Protokolü (MCP) sunucu uygulamasıdır. MCP protokolü ile Xero'nun API'si arasında bir köprü sağlayarak, Xero'nun muhasebe ve iş özelliklerine standartlaştırılmış erişim imkanı sunar.

Özellikler

• Özel bağlantılarla Xero OAuth2 kimlik doğrulaması
• Kişi yönetimi
• Hesap Planı yönetimi
• Fatura oluşturma ve yönetimi
• MCP protokol uyumluluğu

Ön Koşullar

• Node.js (v18 veya üstü)
• npm veya pnpm
• API kimlik bilgilerine sahip bir Xero geliştirici hesabı

Belgeler ve Bağlantılar

• Xero Genel API Belgeleri
• Xero API Gezgini
• Xero OpenAPI Spesifikasyonları
• Xero-Node Genel API SDK Belgeleri
• Geliştirici Belgeleri

Kurulum

Bir Xero Hesabı Oluşturun

Henüz bir Xero hesabınız ve organizasyonunuz yoksa, ücretsiz deneme sürümünü kullanarak buradan kaydolarak bir tane oluşturabilirsiniz.

Başlangıç için bir Demo Şirket kullanmanızı öneririz, çünkü önceden yüklenmiş bazı örnek verilerle gelir. Oturum açtıktan sonra, sol üstteki açılır menüyü kullanarak ve "Demo Şirket"i seçerek buna geçiş yapın. Demo Şirket'teki verileri sıfırlayabilir veya ülkeyi istediğiniz zaman sol üstteki açılır menüyü kullanıp Xero'm bölümüne giderek değiştirebilirsiniz.

NOT: Bordroya özel sorguları kullanmak için bölge NZ veya UK olmalıdır.

Kimlik Doğrulama

Xero MCP sunucusunda 2 kimlik doğrulama modu desteklenir:

1. Özel Bağlantılar

Bu, belirli bir organizasyon için istemci kimliği ve sırlarını belirtmenize olanak tanıyan, test ve geliştirme için daha iyi bir seçimdir. Ayrıca, bunu Claude Desktop gibi üçüncü taraf MCP istemcilerine entegre ediyorsanız önerilen yaklaşımdır.

Xero Geliştirici Hesabınızı Yapılandırma

Şu talimatları izleyerek bir Özel Bağlantı kurun: https://developer.xero.com/documentation/guides/oauth2/custom-connections/

Gerekli Kapsamlar

Özel bağlantılar, oluşturuldukları zamana bağlı olarak farklı kapsamlar gerektirir. İlgili listedeki tüm kapsamlar özel bağlantınıza eklenmelidir:

Özel Bağlantı Oluşturulma Tarihi	Gerekli Kapsamlar
29 Nis 2026'dan önce	SCOPES_V1 (paketlenmiş izinler)
29 Nis 2026'dan itibaren	SCOPES_V2 (ayrıntılı izinler)

Not: MCP sunucusu önce otomatik olarak V1 kapsamlarını dener ve gerekirse V2'ye geri döner.

XERO_SCOPES ortam değişkenini boşlukla ayrılmış bir kapsam listesi olarak ayarlayarak bunları geçersiz kılabilirsiniz.

MCP Sunucusunu Claude Desktop ile Entegre Etme

MCP sunucusunu Claude'a eklemek için Ayarlar > Geliştirici > Yapılandırmayı düzenle'ye gidin ve claude_desktop_config.json dosyanıza aşağıdakini ekleyin:

{
  "mcpServers": {
    "xero": {
      "command": "npx",
      "args": ["-y", "@xeroapi/xero-mcp-server@latest"],
      "env": {
        "XERO_CLIENT_ID": "your_client_id_here",
        "XERO_CLIENT_SECRET": "your_client_secret_here",
        "XERO_SCOPES": "accounting.invoices accounting.contacts accounting.settings"
      }
    }
  }
}

XERO_SCOPES değişkeni isteğe bağlıdır. Atlanırsa, yukarıda listelenen varsayılan kapsamlar kullanılacaktır.

NOT: Node Sürüm Yöneticisi kullanıyorsanız "command": "npx" bölümünü yürütülebilir dosyanın tam yolu olarak değiştirin, örn: Mac / Linux'ta your_home_directory/.nvm/versions/node/v22.14.0/bin/npx veya Windows'ta "your_home_directory\\.nvm\\versions\\node\\v22.14.0\\bin\\npx"

2. Taşıyıcı Belirteç

Bu, çalışma zamanında birden fazla Xero hesabını destekleyecekseniz ve MCP istemcisinin gerektiğinde bir kimlik doğrulama akışı (PKCE gibi) yürütmesine izin verecekseniz daha iyi bir seçimdir. Bu durumda, aşağıdaki yapılandırmayı kullanın:

{
  "mcpServers": {
    "xero": {
      "command": "npx",
      "args": ["-y", "@xeroapi/xero-mcp-server@latest"],
      "env": {
        "XERO_CLIENT_BEARER_TOKEN": "your_bearer_token"
      }
    }
  }
}

NOT: XERO_CLIENT_BEARER_TOKEN, tanımlanmışsa XERO_CLIENT_ID'e göre öncelikli olacaktır.

Taşıyıcı Belirteç için Gerekli Kapsamlar

Bir taşıyıcı belirteç alırken, uygun kapsamları talep etmelisiniz. Talep etmeniz gereken kapsamlar şunlardır:

Not: Bazı kapsamlar, daha ayrıntılı kapsamlar lehine kullanımdan kaldırılmaktadır. Kullanımdan kaldırma zaman çizelgeleri hakkında ayrıntılar için Xero OAuth 2.0 Kapsamlar belgelerine bakın.

accounting.transactions (Deprecated)
accounting.transactions.read (Deprecated)
accounting.invoices
accounting.invoices.read
accounting.payments
accounting.payments.read
accounting.banktransactions
accounting.banktransactions.read
accounting.manualjournals
accounting.manualjournals.read
accounting.reports.read (Deprecated)
accounting.reports.aged.read
accounting.reports.balancesheet.read
accounting.reports.profitandloss.read
accounting.reports.trialbalance.read
accounting.contacts 
accounting.settings 
payroll.settings 
payroll.employees 
payroll.timesheets

Kullanılabilir MCP Komutları

• list-accounts: Hesap listesini al
• list-contacts: Xero'dan kişi listesini al
• list-credit-notes: Alacak dekontu listesini al
• list-invoices: Fatura listesini al
• list-items: Ürün listesini al
• list-manual-journals: Manuel yevmiye kaydı listesini al
• list-organisation-details: Bir organizasyon hakkında ayrıntıları al
• list-profit-and-loss: Kar ve zarar raporunu al
• list-quotes: Teklif listesini al
• list-tax-rates: Vergi oranları listesini al
• list-payments: Ödeme listesini al
• list-trial-balance: Mizan raporunu al
• list-bank-transactions: Banka hesabı işlemleri listesini al
• list-payroll-employees: Bordro Çalışanları listesini al
• list-report-balance-sheet: Bilanço raporunu al
• list-payroll-employee-leave: Bir Bordro Çalışanının izin kayıtlarını al
• list-payroll-employee-leave-balances: Bir Bordro Çalışanının izin bakiyelerini al
• list-payroll-employee-leave-types: Bordro izin türleri listesini al
• list-payroll-leave-periods: Bir Bordro Çalışanının izin dönemleri listesini al
• list-payroll-leave-types: Xero Bordro'daki tüm mevcut izin türlerinin listesini al
• list-timesheets: Bordro Zaman Çizelgeleri listesini al
• list-aged-receivables-by-contact: Bir kişi için yaşlandırılmış alacakları alır
• list-aged-payables-by-contact: Bir kişi için yaşlandırılmış borçları alır
• list-contact-groups: Kişi grupları listesini al
• list-tracking-categories: Takip kategorileri listesini al
• create-bank-transaction: Yeni bir banka işlemi oluştur
• create-contact: Yeni bir kişi oluştur
• create-credit-note: Yeni bir alacak dekontu oluştur
• create-invoice: Yeni bir fatura oluştur
• create-item: Yeni bir ürün oluştur
• create-manual-journal: Yeni bir manuel yevmiye kaydı oluştur
• create-payment: Yeni bir ödeme oluştur
• create-quote: Yeni bir teklif oluştur
• create-payroll-timesheet: Yeni bir Bordro Zaman Çizelgesi oluştur
• create-tracking-category: Yeni bir takip kategorisi oluştur
• create-tracking-option: Yeni bir takip seçeneği oluştur
• update-bank-transaction: Mevcut bir banka işlemini güncelle
• update-contact: Mevcut bir kişiyi güncelle
• update-invoice: Mevcut bir taslak faturayı güncelle
• update-item: Mevcut bir ürünü güncelle
• update-manual-journal: Mevcut bir manuel yevmiye kaydını güncelle
• update-quote: Mevcut bir taslak teklifi güncelle
• update-credit-note: Mevcut bir taslak alacak dekontunu güncelle
• update-tracking-category: Mevcut bir takip kategorisini güncelle
• update-tracking-options: Takip seçeneklerini güncelle
• update-payroll-timesheet-line: Mevcut bir Bordro Zaman Çizelgesindeki bir satırı güncelle
• approve-payroll-timesheet: Bir Bordro Zaman Çizelgesini Onayla
• revert-payroll-timesheet: Onaylanmış bir Bordro Zaman Çizelgesini geri al
• add-payroll-timesheet-line: Mevcut bir Bordro Zaman Çizelgesine yeni satır ekle
• delete-payroll-timesheet: Mevcut bir Bordro Zaman Çizelgesini sil
• get-payroll-timesheet: Mevcut bir Bordro Zaman Çizelgesini al

Ayrıntılı API belgeleri için lütfen MCP Protokol Spesifikasyonuna bakın.

Geliştiriciler İçin

Kurulum

# Using npm
npm install

# Using pnpm
pnpm install

Derleme Çalıştırma

# Using npm
npm run build

# Using pnpm
pnpm build

Claude Desktop ile Entegrasyon

Geliştirme aşamasındaki Xero MCP sunucunuzu Claude Desktop'a bağlamak için Ayarlar > Geliştirici > Yapılandırmayı düzenle'ye gidin ve claude_desktop_config.json dosyanıza aşağıdakini ekleyin:

NOT: Windows için args yolunun klasörler arasındaki \ karakterini kaçırdığından emin olun, yani "C:\\projects\xero-mcp-server\\dist\\index.js"

{
  "mcpServers": {
    "xero": {
      "command": "node",
      "args": ["insert-your-file-path-here/xero-mcp-server/dist/index.js"],
      "env": {
        "XERO_CLIENT_ID": "your_client_id_here",
        "XERO_CLIENT_SECRET": "your_client_secret_here"
      }
    }
  }
}

Lisans

MIT

Güvenlik

Lütfen .env dosyanızı veya hassas kimlik bilgilerinizi sürüm kontrolüne göndermeyin (güvenli bir varsayılan olarak .gitignore dosyasına dahil edilmiştir.)