Xledger MCP Server

An MCP (Model Context Protocol) server that provides read-only access to the Xledger accounting system via its GraphQL API.

Use it with Claude, VS Code Copilot, or any MCP-compatible AI assistant to query your financial data — invoices, account balances, projects, timesheets, and more.

Features

• 9 read-only tools covering core accounting data
• Compatible with Xledger GraphQL API v2
• Token-based authentication (no OAuth complexity)
• Zero runtime dependencies beyond the MCP SDK
• TypeScript with full type safety

Tools

Tool	Description
get_ar_transactions	Customer invoices (Accounts Receivable) — filter by date, outstanding only
get_ap_transactions	Supplier invoices (Accounts Payable) — filter by date, outstanding only
get_account_balances	GL account balances by fiscal year and period
get_projects	Project financials — revenue, cost, hours, billability
get_timesheets	Timesheet entries — hours per employee per project
get_journal_entries	Raw GL transactions with account, amount, project
get_employees	Employee list with employment dates
get_customers	Customer lookup with name search
get_revenue_summary	Aggregated revenue by customer for a date period

All tools are annotated with readOnlyHint: true — they never modify data in Xledger.

Quick Start

Prerequisites

• Node.js 18+
• A Xledger account with GraphQL API access
• An API token (generate at: Xledger > Administration > System Access > GraphQL/API tokens)

Install and Build

git clone https://github.com/Eyevinn/xledger-mcp-server.git
cd xledger-mcp-server
npm install
npm run build

Configure

Set the required environment variable:

export XLEDGER_GRAPHQL_TOKEN=your-token-here

Variable	Required	Default	Description
XLEDGER_GRAPHQL_TOKEN	Yes	—	Your Xledger API token
XLEDGER_API_URL	No	https://www.xledger.net/graphql	API endpoint (use https://demo.xledger.net/graphql for testing)

Run

npm start

The server communicates over stdio — it's designed to be launched by an MCP client, not run standalone.

Configuration

Claude Desktop / Claude Code

Add to your Claude configuration (~/.claude/settings.json or Claude Desktop config):

{
  "mcpServers": {
    "xledger": {
      "command": "node",
      "args": ["/path/to/xledger-mcp-server/dist/index.js"],
      "env": {
        "XLEDGER_GRAPHQL_TOKEN": "your-token-here"
      }
    }
  }
}

VS Code (GitHub Copilot)

Add to .vscode/mcp.json:

{
  "servers": {
    "xledger": {
      "command": "node",
      "args": ["/path/to/xledger-mcp-server/dist/index.js"],
      "env": {
        "XLEDGER_GRAPHQL_TOKEN": "your-token-here"
      }
    }
  }
}

Tool Details

get_ar_transactions

Get customer invoices with optional filters.

Parameters:

• first (number, default: 50) — Number of records (max 200)
• outstandingOnly (boolean, default: false) — Only unpaid invoices
• fromDate (string, YYYY-MM-DD) — Invoice date from
• toDate (string, YYYY-MM-DD) — Invoice date to

get_ap_transactions

Get supplier invoices with optional filters. Same parameters as get_ar_transactions.

get_account_balances

Get GL account balances.

Parameters:

• fiscalYear (number) — Fiscal year, defaults to current year
• periodNumber (number, 1-12) — Month. Returns YTD if omitted
• first (number, default: 200) — Number of records (max 500)

get_projects

Get projects with financial data.

Parameters:

• first (number, default: 100) — Number of records (max 500)
• activeOnly (boolean, default: true) — Only active projects
• billableOnly (boolean, default: false) — Only billable projects

get_timesheets

Get timesheet entries.

Parameters:

• first (number, default: 100) — Number of records (max 500)
• fromDate / toDate (string, YYYY-MM-DD) — Date range
• invoicedOnly (boolean) — Only invoiced entries
• notInvoiced (boolean) — Only uninvoiced entries

get_journal_entries

Get raw GL transactions.

Parameters:

• first (number, default: 50) — Number of records (max 200)
• fromDate / toDate (string, YYYY-MM-DD) — Date range (uses createdAt as proxy since postedDate is not filterable in API v2)
• fiscalYear (number) — Client-side fiscal year filter

get_employees

Get employee list.

Parameters:

• first (number, default: 100) — Number of records
• activeOnly (boolean, default: true) — Only currently employed

get_customers

Get customers (subledgers).

Parameters:

• first (number, default: 100) — Number of records
• search (string) — Partial name/code match (client-side)

get_revenue_summary

Get aggregated revenue by customer.

Parameters:

• fromDate (string, YYYY-MM-DD, required) — Period start
• toDate (string, YYYY-MM-DD, required) — Period end

Xledger API v2 Notes

This server is compatible with Xledger's GraphQL API v2 schema, which introduced several changes:

• Filter syntax: Direct field suffixes (e.g., invoiceDate_gte) instead of { AND: [{ field, op, value }] }
• OrderBy: Array of { field, direction } enums instead of single object
• Removed filters: Some fields are no longer filterable (fiscalYear on account balances, description on subledgers, billable on projects, postedDate on journal entries). These are handled with client-side filtering.
• SystemValue: Uses .name instead of .description

Development

npm install
npm run build        # Compile TypeScript
npm test             # Run tests
npm run dev          # Watch mode (recompile on changes)
npm run lint         # Type-check without emitting

Security

• The API token grants read access scoped to your Xledger tenant
• Never commit tokens to version control — use environment variables
• All tools are read-only (no mutations)
• Consider using Xledger's token scope controls to limit access to only the data you need

License

MIT — see LICENSE

About Eyevinn Technology

Eyevinn Technology is a Stockholm-based consultancy specializing in video streaming technology. We contribute to the open source community through our GitHub organization and Open Source Cloud platform.