# Xledger Mcp Server

> MCP server for Xledger GraphQL API — read-only access to accounting data

- **Type:** MCP server
- **Install:** `agentstack add mcp-eyevinn-xledger-mcp-server`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Eyevinn](https://agentstack.voostack.com/s/eyevinn)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Eyevinn](https://github.com/Eyevinn)
- **Source:** https://github.com/Eyevinn/xledger-mcp-server

## Install

```sh
agentstack add mcp-eyevinn-xledger-mcp-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Xledger MCP Server

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that provides read-only access to the [Xledger](https://www.xledger.com) 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

```bash
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:

```bash
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

```bash
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):

```json
{
  "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`:

```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

```bash
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](LICENSE)

## About Eyevinn Technology

[Eyevinn Technology](https://www.eyevinn.se) is a Stockholm-based consultancy specializing in video streaming technology. We contribute to the open source community through our [GitHub organization](https://github.com/Eyevinn) and [Open Source Cloud](https://www.osaas.io) platform.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Eyevinn](https://github.com/Eyevinn)
- **Source:** [Eyevinn/xledger-mcp-server](https://github.com/Eyevinn/xledger-mcp-server)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-eyevinn-xledger-mcp-server
- Seller: https://agentstack.voostack.com/s/eyevinn
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.