Xledger MCP Server

Xledger MCP服务器

一 MCP（模型上下文协议） 提供对的只读访问的服务器 Xledger 会计系统通过其GraphQL API。

将其与Claude、VS Code Copilot或任何兼容MCP的AI助手一起使用，以查询您的财务数据——发票、账户余额、项目、时间表等。

特性

• 涵盖核心会计数据的9个只读工具
• 与Xledger GraphQL API v2兼容
• 基于令牌的身份验证（无OAuth复杂性）
• MCP SDK之外的零运行时依赖关系
• 具有完全类型安全的TypeScript

工具

所有工具都带有注释 readOnlyHint: true --他们从不修改Xledger中的数据。

快速开始

先决条件

• Node.js 18+
• 具有GraphQL API访问权限的Xledger帐户
• API令牌（生成位置：Xledger>Administration>System Access>GraphQL/API令牌）

安装和构建

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

配置

设置所需的环境变量：

export XLEDGER_GRAPHQL_TOKEN=your-token-here

跑

npm start

服务器通过stdio进行通信——它被设计为由MCP客户端启动，而不是独立运行。

配置

克劳德桌面/克劳德代码

添加到您的Claude配置(~/.claude/settings.json 或Claude桌面配置）：

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

VS代码（GitHub副本）

添加 .vscode/mcp.json:

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

工具详细信息

获取_交易

使用可选过滤器获取客户发票。

参数：

• first （数字，默认值：50）--记录数（最多200）
• outstandingOnly （布尔值，默认值：false）--仅限未付发票
• fromDate （字符串，YYYY-MM-DD）--发票日期从
• toDate （字符串，YYYY-MM-DD）--发票日期到

get_ap_transactions

使用可选过滤器获取供应商发票。参数与 get_ar_transactions.

get_count_balances

获取总账账户余额。

参数：

• fiscalYear （数字）——会计年度，默认为本年度
• periodNumber （数字，1-12）--月份。如果省略，则返回年初至今
• first （数字，默认值：200）--记录数（最多500）

get_项目

获取包含财务数据的项目。

参数：

• first （数字，默认值：100）--记录数（最多500）
• activeOnly （boolean，默认值：true）--仅限活动项目
• billableOnly （boolean，默认值：false）--仅计费项目

获取时间表

获取时间表条目。

参数：

• first （数字，默认值：100）--记录数（最多500）
• fromDate / toDate （字符串，YYYY-MM-DD）--日期范围
• invoicedOnly （boolean）--仅发票条目
• notInvoiced （boolean）--仅限未发音的条目

get_journal_entries

获取原始总账交易记录。

参数：

• first （数字，默认值：50）--记录数（最多200）
• fromDate / toDate （字符串，YYYY-MM-DD）--日期范围（使用 createdAt 作为代理，因为 postedDate 在API v2中不可筛选）
• fiscalYear （number）--客户端会计年度筛选器

get_员工

获取员工名单。

参数：

• first （number，默认值：100）--记录数
• activeOnly （boolean，默认值：true）--仅当前使用

get_客户

获取客户（明细账）。

参数：

• first （number，默认值：100）--记录数
• search （string）--部分名称/代码匹配（客户端）

get_revenue_summary

按客户获得汇总收入。

参数：

• fromDate （字符串，YYYY-MM-DD，必填）--时段开始
• toDate （字符串，YYYY-MM-DD，必填）--周期结束

Xledger API v2注释

此服务器与Xledger的GraphQL API v2架构兼容，该架构引入了几个更改：

• 筛选器语法：直接字段后缀（例如。， invoiceDate_gte)而不是 { AND: [{ field, op, value }] }
• 排序依据：数组 { field, direction } 枚举而不是单个对象
• 已删除筛选器：某些字段不再可筛选(fiscalYear 账户余额， description 在子磨边机上， billable 在项目上， postedDate 日记账分录）。这些是通过客户端过滤处理的。
• 系统价值：用途 .name 而不是 .description

发展

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

安全

• API令牌授予Xledger租户范围内的读取访问权限
• 永远不要将令牌提交到版本控制中——使用环境变量
• 所有工具都是只读的（没有突变）
• 考虑使用Xledger的令牌范围控件来限制对所需数据的访问

许可证

麻省理工学院——见 许可证

关于Eyevinn科技

Eyevinn科技 是一家总部位于斯德哥尔摩的咨询公司，专门从事视频流技术。我们通过我们的 和 开源云 平台。