Xero MCP Server

oficial

Interaja com os dados contábeis da sua empresa usando nosso servidor MCP oficial.

Documentação

Servidor MCP Xero

Esta é uma implementação de servidor do Model Context Protocol (MCP) para o Xero. Ela fornece uma ponte entre o protocolo MCP e a API do Xero, permitindo acesso padronizado aos recursos contábeis e empresariais do Xero.

Funcionalidades

Autenticação OAuth2 do Xero com conexões personalizadas
Gerenciamento de contatos
Gerenciamento do plano de contas
Criação e gerenciamento de faturas
Conformidade com o protocolo MCP

Pré-requisitos

Node.js (v18 ou superior)
npm ou pnpm
Uma conta de desenvolvedor Xero com credenciais de API

Documentação e Links

Configuração

Criar uma Conta Xero

Se você ainda não tem uma conta e organização Xero, pode criar uma inscrevendo-se aqui usando o teste gratuito.

Recomendamos começar com uma Empresa de Demonstração, pois ela vem com alguns dados de exemplo pré-carregados. Depois de fazer login, alterne para ela usando o menu suspenso no canto superior esquerdo e selecionando "Empresa de Demonstração". Você pode redefinir os dados de uma Empresa de Demonstração, ou alterar o país, a qualquer momento usando o menu suspenso no canto superior esquerdo e navegando para Meu Xero.

NOTA: Para usar consultas específicas da folha de pagamento, a região deve ser NZ ou UK.

Autenticação

Há 2 modos de autenticação suportados no servidor MCP Xero:

1. Conexões Personalizadas

Esta é uma escolha melhor para testes e desenvolvimento, que permite especificar o ID do cliente e os segredos para uma organização específica. Também é a abordagem recomendada se você estiver integrando isso a clientes MCP de terceiros, como o Claude Desktop.

Configurando sua conta de Desenvolvedor Xero

Configure uma Conexão Personalizada seguindo estas instruções: https://developer.xero.com/documentation/guides/oauth2/custom-connections/

Escopos Necessários

Conexões personalizadas exigem escopos diferentes dependendo de quando foram criadas. Todos os escopos na lista relevante devem ser adicionados à sua conexão personalizada:

Conexão Personalizada Criada	Escopos Necessários
Antes de 29 de abril de 2026	SCOPES_V1 (permissões agrupadas)
A partir de 29 de abril de 2026	SCOPES_V2 (permissões granulares)

Nota: O servidor MCP tenta automaticamente os escopos V1 primeiro e recorre aos V2, se necessário.

Você pode substituí-los definindo a variável de ambiente XERO_SCOPES com uma lista de escopos separados por espaços.

Integrando o servidor MCP com o Claude Desktop

Para adicionar o servidor MCP ao Claude, vá para Configurações > Desenvolvedor > Editar configuração e adicione o seguinte ao seu arquivo claude_desktop_config.json:

{
  "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"
      }
    }
  }
}

A variável XERO_SCOPES é opcional. Se omitida, os escopos padrão listados acima serão usados.

NOTA: Se você estiver usando o Node Version Manager na seção "command": "npx", altere para o caminho completo do executável, ou seja: your_home_directory/.nvm/versions/node/v22.14.0/bin/npx no Mac / Linux ou "your_home_directory\\.nvm\\versions\\node\\v22.14.0\\bin\\npx" no Windows

2. Token de Portador

Esta é uma escolha melhor se você precisar oferecer suporte a várias contas Xero em tempo de execução e permitir que o cliente MCP execute um fluxo de autenticação (como PKCE) conforme necessário. Neste caso, use a seguinte configuração:

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

NOTA: O XERO_CLIENT_BEARER_TOKEN terá precedência sobre o XERO_CLIENT_ID se definido.

Escopos Necessários para Token de Portador

Ao obter um token de portador, você deve solicitar os escopos apropriados. Os escopos que você deve solicitar são:

Nota: Alguns escopos estão sendo descontinuados em favor de escopos mais granulares. Consulte a documentação de Escopos do Xero OAuth 2.0 para detalhes sobre os cronogramas de descontinuação.

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

Comandos MCP Disponíveis

list-accounts: Recuperar uma lista de contas
list-contacts: Recuperar uma lista de contatos do Xero
list-credit-notes: Recuperar uma lista de notas de crédito
list-invoices: Recuperar uma lista de faturas
list-items: Recuperar uma lista de itens
list-manual-journals: Recuperar uma lista de diários manuais
list-organisation-details: Recuperar detalhes sobre uma organização
list-profit-and-loss: Recuperar um relatório de lucros e perdas
list-quotes: Recuperar uma lista de orçamentos
list-tax-rates: Recuperar uma lista de alíquotas de impostos
list-payments: Recuperar uma lista de pagamentos
list-trial-balance: Recuperar um relatório de balancete
list-bank-transactions: Recuperar uma lista de transações de conta bancária
list-payroll-employees: Recuperar uma lista de Funcionários da Folha de Pagamento
list-report-balance-sheet: Recuperar um relatório de balanço patrimonial
list-payroll-employee-leave: Recuperar os registros de licença de um Funcionário da Folha de Pagamento
list-payroll-employee-leave-balances: Recuperar os saldos de licença de um Funcionário da Folha de Pagamento
list-payroll-employee-leave-types: Recuperar uma lista de tipos de licença da Folha de Pagamento
list-payroll-leave-periods: Recuperar uma lista dos períodos de licença de um Funcionário da Folha de Pagamento
list-payroll-leave-types: Recuperar uma lista de todos os tipos de licença disponíveis na Folha de Pagamento do Xero
list-timesheets: Recuperar uma lista de Quadros de Horários da Folha de Pagamento
list-aged-receivables-by-contact: Recupera valores a receber vencidos para um contato
list-aged-payables-by-contact: Recupera valores a pagar vencidos para um contato
list-contact-groups: Recuperar uma lista de grupos de contatos
list-tracking-categories: Recuperar uma lista de categorias de rastreamento
create-bank-transaction: Criar uma nova transação bancária
create-contact: Criar um novo contato
create-credit-note: Criar uma nova nota de crédito
create-invoice: Criar uma nova fatura
create-item: Criar um novo item
create-manual-journal: Criar um novo diário manual
create-payment: Criar um novo pagamento
create-quote: Criar um novo orçamento
create-payroll-timesheet: Criar um novo Quadro de Horários da Folha de Pagamento
create-tracking-category: Criar uma nova categoria de rastreamento
create-tracking-option: Criar uma nova opção de rastreamento
update-bank-transaction: Atualizar uma transação bancária existente
update-contact: Atualizar um contato existente
update-invoice: Atualizar uma fatura rascunho existente
update-item: Atualizar um item existente
update-manual-journal: Atualizar um diário manual existente
update-quote: Atualizar um orçamento rascunho existente
update-credit-note: Atualizar uma nota de crédito rascunho existente
update-tracking-category: Atualizar uma categoria de rastreamento existente
update-tracking-options: Atualizar opções de rastreamento
update-payroll-timesheet-line: Atualizar uma linha em um Quadro de Horários da Folha de Pagamento existente
approve-payroll-timesheet: Aprovar um Quadro de Horários da Folha de Pagamento
revert-payroll-timesheet: Reverter um Quadro de Horários da Folha de Pagamento aprovado
add-payroll-timesheet-line: Adicionar nova linha em um Quadro de Horários da Folha de Pagamento existente
delete-payroll-timesheet: Excluir um Quadro de Horários da Folha de Pagamento existente
get-payroll-timesheet: Recuperar um Quadro de Horários da Folha de Pagamento existente

Para documentação detalhada da API, consulte a Especificação do Protocolo MCP.

Para Desenvolvedores

Instalação

# Using npm
npm install

# Using pnpm
pnpm install

Executar uma compilação

# Using npm
npm run build

# Using pnpm
pnpm build

Integrando com o Claude Desktop

Para vincular seu servidor MCP Xero em desenvolvimento ao Claude Desktop, vá para Configurações > Desenvolvedor > Editar configuração e adicione o seguinte ao seu arquivo claude_desktop_config.json:

NOTA: Para Windows, certifique-se de que o caminho args escape o \ entre pastas, ou seja, "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"
      }
    }
  }
}

Licença

MIT

Segurança

Por favor, não faça commit do seu arquivo .env ou de quaisquer credenciais sensíveis no controle de versão (ele está incluído no .gitignore como um padrão seguro.)