Kledo API MCP

Kledo MCP服务器

Kledo会计软件API的模型上下文协议（MCP）服务器-使人工智能助手能够与您的Kledo数据交互，用于财务报告、分析、客户管理和商业智能。

这是什么？

MCP服务器，将人工智能助手（如Claude）连接到Kledo会计API，实现财务数据、客户分析和业务报告的自然语言查询。

🎯 主要特点

• 24种生产就绪工具 -全面覆盖Kledo API终点
• 收入与财务分析 -发票跟踪、收入报告、应收账款管理
• 客户智能 -客户排名、交易历史、联系人管理
• 产品和库存 -产品查找、SKU搜索、库存洞察
• 订单和交货跟踪 -销售订单、采购订单、交货状态
• 双语支持 -理解印尼语和英语查询
• 智能缓存 -可配置的缓存可实现最佳性能
• 类型安全 -全面的类型提示贯穿始终

🚀 2分钟快速入门

首次设置：

1. 克隆并安装：

随着 uv （推荐）：

   git clone https://github.com/efacsen/kledo-api-mcp.git
   cd kledo-api-mcp
   uv pip install -e .

随着 pip:

   git clone https://github.com/efacsen/kledo-api-mcp.git
   cd kledo-api-mcp
   pip install -e .

> 没有 uv？安装它： curl -LsSf https://astral.sh/uv/install.sh | sh

1. 运行安装向导：

   kledo-mcp --setup

交互式向导将：

- ✓ 提示输入您的Kledo API密钥 - ✓ 根据Kledo API实时验证您的连接 - ✓ 将配置保存到 ~/.kledo/.env （跨项目持续）

1. 获取您的Claude桌面配置：

   kledo-mcp --show-config

这将输出精确的JSON以粘贴到您的Claude Desktop配置文件中：

- macOS： ~/Library/Application Support/Claude/claude_desktop_config.json - 窗户： %APPDATA%\Claude\claude_desktop_config.json - Linux： ~/.config/Claude/claude_desktop_config.json

1. 重新启动克劳德桌面 -完成！ 🎉

获取您的Kledo API密钥：

1. 登录到 App.kledo.com
2. 首选 设置→ 集成→ API
3. 创建新的个人访问令牌

需要帮助？ 看 故障排除 在......下面

🛠️ 可用工具（共24个）

收入（3个工具）

• revenue_summary -任何时期的收入（已付发票，含税明细）
• revenue_receivables -未付发票：列表/账龄区间/帕累托集中度
• revenue_ranking -按客户或天数排名的收入

发票（3个工具）

• invoice_list -列出销售或采购发票(type: sales|purchase)
• invoice_get -按ID列出的详细发票信息
• invoice_summarize -按客户/供应商列出的发票总额或未付明细

订单（2个工具）

• order_list -列出销售或采购订单(type: sales|purchase)
• order_get -按ID列出的订单详细信息

产品（2个工具）

• product_list -列出具有可选搜索和库存的产品
• product_get -按ID或SKU/代码列出的产品详细信息

客户/联系人（2个工具）

• contact_list -列出客户和供应商
• contact_get -联系方式或交易历史(view: detail|transactions)

交付（2个工具）

• delivery_list -列出带有日期/状态过滤器的交付
• delivery_get -交货详情或待发货(view: detail|pending)

金融（2个工具）

• financial_summary -按客户、销售代表或供应商列出的销售或采购摘要
• financial_balances -当前银行账户余额

分析和佣金（3个工具）

• analytics_compare -比较不同时期或销售代表的收入或未偿还金额
• analytics_targets -销售目标：报告/表现不佳者/设定目标
• commission_report -每个代表或所有代表的佣金计算（分层或统一费率）

销售（2个工具）

• sales_rep_report -一段时间内销售代表收入明细
• sales_rep_list -列出所有销售代表

实用程序（2个工具）

• utility_cache -缓存统计数据或清除(action: stats|clear)
• utility_test_connection -测试Kledo API连接和身份验证状态

📦 安装

先决条件

• Python 3.11或更高版本
• 具有API访问权限的Kledo帐户
• Claude Desktop或任何支持MCP的AI IDE

标准安装

随着 uv （推荐）：

git clone https://github.com/efacsen/kledo-api-mcp.git
cd kledo-api-mcp
uv pip install -e .

随着 pip:

git clone https://github.com/efacsen/kledo-api-mcp.git
cd kledo-api-mcp
pip install -e .

这 kledo-mcp 命令现在可用！

获取您的Kledo API密钥

1. 登录您的Kledo帐户 https://kledo.com
2. 导航至 设置 → 集成 → API
3. 点击 生成新的API密钥
4. 复制密钥（以开头 kledo_pat_)

运行时，安装向导将提示您输入此密钥 kledo-mcp 这是第一次。

Claude桌面配置

最简单的方法是运行安装向导：

kledo-mcp --show-config

这将显示具有正确路径的Claude Desktop配置。只需复制和粘贴！

安全说明：永远不要将API密钥提交给版本控制。

🚀 部署和生产设置

MCP服务器支持多种部署场景，配置灵活：

环境变量（建议用于生产）

对于Docker、Kubernetes和基础设施即代码部署：

export KLEDO_API_KEY="your_api_key_here"
export KLEDO_BASE_URL="https://api.kledo.com/api/v1"
kledo-mcp  # Starts immediately, skips setup wizard

非常适合：

• Docker容器
• Kubernetes部署
• 地形/云层
• CI/CD管道
• 非交互式部署

配置文件位置

服务器按照以下优先级顺序检查配置：

1. 环境变量 （最高优先级）

- KLEDO_API_KEY - KLEDO_BASE_URL

1. 用户配置目录 （持续）

- ~/.kledo/.env -跨项目/克隆持久化

1. XDG配置目录 （Unix/Linux标准）

- ~/.config/kledo/.env

1. 系统配置目录

- /etc/kledo/.env

1. 项目目录 （回退）

- ./.env -项目根

部署场景

场景A：交互式服务器（SSH）

ssh ubuntu@your-server
cd ~/kledo-api-mcp
kledo-mcp
# Wizard prompts for API key
# Saves to ~/.kledo/.env automatically

场景B：Docker容器

FROM python:3.11-slim
RUN pip install kledo-api-mcp
ENV KLEDO_API_KEY=your_key_here
ENV KLEDO_BASE_URL=https://api.kledo.com/api/v1
CMD ["kledo-mcp"]

场景C:Kubernetes Pod

apiVersion: v1
kind: Pod
spec:
  containers:
  - name: kledo-mcp
    image: kledo-mcp:latest
    env:
    - name: KLEDO_API_KEY
      valueFrom:
        secretKeyRef:
          name: kledo-secrets
          key: api_key
    - name: KLEDO_BASE_URL
      value: https://api.kledo.com/api/v1

场景D：预配置的VM映像

# During image creation
mkdir -p ~/.kledo
cat > ~/.kledo/.env << EOF
KLEDO_API_KEY=your_key
KLEDO_BASE_URL=https://api.kledo.com/api/v1
EOF

# Later, on cloned instances
kledo-mcp  # Automatically finds ~/.kledo/.env

配置优先

服务器使用此决策树：

Does environment variables have KLEDO_API_KEY?
  ├─ YES → Use environment variables
  └─ NO → Check ~/.kledo/.env
           ├─ YES → Use ~/.kledo/.env
           └─ NO → Check ~/.config/kledo/.env
                    ├─ YES → Use ~/.config/kledo/.env
                    └─ NO → Check /etc/kledo/.env
                             ├─ YES → Use /etc/kledo/.env
                             └─ NO → Run interactive setup wizard

这意味着：

• 环境变量始终覆盖.env文件
• 配置后，将跳过向导
• 重新安装后配置仍然有效（在~/.kledo/中）
• 完全支持非交互式部署

🚀 使用示例

获得每月收入

问你的AI助手：

"What's this month's revenue?"
"Berapa revenue bulan ini?"

助理将使用 revenue_summary 工具和纳税明细表收入数据。

销售代表绩效

问：

"Show sales rep performance for January"
"Siapa sales rep dengan revenue tertinggi bulan ini?"

获取详细的绩效指标，包括收入、发票计数和每位代表的最高交易额。

未付发票

问：

"Show outstanding invoices"
"Siapa yang belum bayar?"

查看所有未付款和部分付款的发票，包括客户详细信息和金额。

顶级客户

问：

"Who are our top 10 customers this month?"
"Customer dengan revenue tertinggi?"

按收入、发票数量和平均发票价值获取客户排名。

产品搜索

问：

"Find product with SKU ABC123"
"Show all products in category Paint"

按SKU、名称或类别搜索和筛选产品。

🔧 配置

缓存配置

服务器使用智能缓存来减少API调用。在中配置 config/cache_config.yaml:

default:
  ttl: 300
  max_size: 1000

categories:
  invoices:
    ttl: 60
  products:
    ttl: 3600
  contacts:
    ttl: 1800

端点配置

API终结点配置在 config/endpoints.yaml所有端点都是针对Kledo API v1预先配置的。

环境变量

🐛 故障排除

设置和首次运行问题

安装向导无法启动：

# Verify installation
pip install -e .

# Try explicit setup
kledo-mcp --setup

“无效的API密钥”错误：

1. 验证您的API密钥以 kledo_pat_
2. 复制时检查是否有多余的空格
3. 直接测试密钥：

   kledo-mcp --test

1. 如果需要，从Kledo仪表板生成新密钥

配置未保存：

# Check .env was created
ls -la .env

# Force re-initialization
kledo-mcp --init

安装过程中“连接失败”：

1. 验证您的互联网连接
2. 检查Kledo API状态： https://status.kledo.com
3. 卷曲测试：

   curl -H "Authorization: Bearer YOUR_API_KEY" \
        https://api.kledo.com/api/v1/finance/account

Claude Desktop未显示服务器：

1. 跑 kledo-mcp --show-config 并复制输出
2. 验证JSON语法（使用 Jsonlin.com)
3. 检查配置文件位置：

   # macOS
   cat ~/Library/Application\ Support/Claude/claude_desktop_config.json

   # Linux
   cat ~/.config/Claude/claude_desktop_config.json

1. 完全重新启动Claude Desktop（退出并重新打开）
2. 检查克劳德日志：

   # macOS
   tail -f ~/Library/Logs/Claude/mcp*.log

还在卡住吗？

通过以下方式打开问题：

• 输出 kledo-mcp --version
• 输出 kledo-mcp --test
• 安装向导中的任何错误消息

______________________________________________________________________

MCP服务器未在Claude中显示

1. 检查配置文件位置：

- macOS： ~/Library/Application Support/Claude/claude_desktop_config.json - 窗户： %APPDATA%\Claude\claude_desktop_config.json - Linux： ~/.config/Claude/claude_desktop_config.json

1. 验证JSON语法 -使用JSON验证器检查错误

1. 检查绝对路径 -确保 cwd 指向正确的绝对路径

1. 重新启动克劳德 完全（而不仅仅是刷新）

1. 检查日志：

   # macOS/Linux
   tail -f ~/Library/Logs/Claude/mcp*.log

   # Windows
   # Check %LOCALAPPDATA%\Claude\Logs\

身份验证错误

1. 验证API密钥 在 .env 文件
2. 检查API密钥权限 在Kledo仪表板中
3. 卷曲测试：

   curl -H "Authorization: Bearer YOUR_API_KEY" \
        https://api.kledo.com/api/v1/finance/account

导入错误

如果你看到 ModuleNotFoundError:

# Reinstall in development mode
pip install -e .

# Or install dependencies manually
pip install -r requirements.txt

缓存问题

如果看到过时数据，请清除缓存：

问你的AI助手：

"Clear Kledo cache"

或在中禁用缓存 .env:

CACHE_ENABLED=false

🤝 贡献

欢迎投稿！拜托：

1. 分叉存储库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 提交您的更改(git commit -m 'Add amazing feature')
4. 推到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

开发设置

# Clone your fork
git clone https://github.com/YOUR_USERNAME/kledo-api-mcp.git
cd kledo-api-mcp

# Install with dev dependencies (uv recommended)
uv pip install -e ".[dev]"
# or: pip install -e ".[dev]"

# Run tests
uv run pytest tests/

# Run linters
uv run ruff check src/
uv run mypy src/

📄 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

🙏 致谢

• 建于 模型上下文协议（MCP） 通过Anthropic
• 与集成 克莱多 会计软件API

📞 支持

• 问题:
• Kledo API文件: https://api-docs.kledo.com/
• MCP文件: https://modelcontextprotocol.io/

______________________________________________________________________

制作❤️ 用于智能业务分析