Marqeta DiVA API MCP Server

Marqeta DiVA API MCP服务器

](https://badge.fury.io/py/marqeta-diva-mcp)  

模型上下文协议（MCP）服务器，提供对Marqeta DiVA（数据洞察、可视化和分析）API的编程访问。该服务器使AI助手和应用程序能够从Marqeta平台检索聚合的生产数据，用于报告、分析和数据驱动的业务决策。

注： 这是一个非官方的社区项目，没有得到Marqeta的正式支持。

特性

核心功能（始终可用）

• 交易数据：访问授权、结算、清算、拒绝和加载
• 财务数据：检索程序余额、结算余额和活动余额
• 卡和用户数据：通过灵活的过滤获取卡和用户详细信息
• 退单数据：访问退款状态和详细信息
• 元数据工具：发现可用视图并检索模式定义
• 导出工具：将数据导出为JSON或CSV文件
• 速率限制：符合API限制的内置速率限制（每5分钟300个请求）
• 错误处理：通过有意义的消息进行全面的错误处理
• 灵活查询：支持过滤、排序、字段选择、日期范围等

可选RAG功能（需要 [rag] 额外）

• 本地存储：将完整的交易数据存储在SQLite中（绕过MCP令牌限制）
• 语义搜索：使用AI嵌入对交易数据进行自然语言查询
• 向量存储：ChromaDB集成用于基于相似性的事务搜索
• 离线分析：在没有API调用或令牌限制的情况下查询本地数据

先决条件

• Python 3.10或更高版本
• 紫外线 包管理器（用于与一起运行 uvx)
• Marqeta DiVA API证书（应用令牌、访问令牌和程序名称）

安装

选项1：使用uvx运行（推荐）

无需安装！ uvx 将在您运行服务器时自动处理依赖关系。

仅适用于基本功能：

uvx marqeta-diva-mcp

对于RAG功能（本地存储+语义搜索）：

uvx --with marqeta-diva-mcp[rag] marqeta-diva-mcp

选项2：传统安装

基本安装（仅核心功能）：

pip install marqeta-diva-mcp

具有RAG功能（建议用于高级分析）：

pip install marqeta-diva-mcp[rag]

来源：

cd marqeta-diva-mcp
pip install -e .              # Basic features
pip install -e ".[rag]"       # With RAG features

配置

1. 复制示例环境文件：

cp .env.example .env

1. 编辑 .env 并添加您的Marqeta DiVA API证书：

# Required: Marqeta DiVA API credentials
MARQETA_APP_TOKEN=your_application_token_here
MARQETA_ACCESS_TOKEN=your_access_token_here
MARQETA_PROGRAM=your_program_name_here

# Optional: Enable local storage and RAG features
# Requires: pip install marqeta-diva-mcp[rag]
# ENABLE_LOCAL_STORAGE=true

如何获取证书：

• 联系您的Marqeta代表，或
• 通过Marqeta仪表板生成（报告部分）

启用RAG功能：

要使用本地存储、语义搜索和其他RAG功能：

1. 安装RAG依赖项： pip install marqeta-diva-mcp[rag]
2. 设置环境变量： ENABLE_LOCAL_STORAGE=true
3. 重新启动MCP服务器

启用后，您将在日志中看到此消息：

[MCP Server] Local storage and RAG features ENABLED

禁用时（默认）：

[MCP Server] Local storage and RAG features DISABLED (set ENABLE_LOCAL_STORAGE=true to enable)

用法

在本地运行服务器

带uvx（推荐）

cd marqeta-diva-mcp
uvx marqeta-diva-mcp

使用Python

cd marqeta-diva-mcp
python -m marqeta_diva_mcp.server

添加到Claude桌面

将此配置添加到您的Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%/Claude/claude_desktop_config.json

使用uvx（推荐）

基本配置（仅核心功能）：

{
  "mcpServers": {
    "marqeta-diva": {
      "command": "uvx",
      "args": ["marqeta-diva-mcp"],
      "env": {
        "MARQETA_APP_TOKEN": "your_application_token",
        "MARQETA_ACCESS_TOKEN": "your_access_token",
        "MARQETA_PROGRAM": "your_program_name"
      }
    }
  }
}

具有RAG功能（本地存储+语义搜索）：

{
  "mcpServers": {
    "marqeta-diva": {
      "command": "uvx",
      "args": ["--with", "marqeta-diva-mcp[rag]", "marqeta-diva-mcp"],
      "env": {
        "MARQETA_APP_TOKEN": "your_application_token",
        "MARQETA_ACCESS_TOKEN": "your_access_token",
        "MARQETA_PROGRAM": "your_program_name",
        "ENABLE_LOCAL_STORAGE": "true"
      }
    }
  }
}

使用Python

基本配置（仅核心功能）：

{
  "mcpServers": {
    "marqeta-diva": {
      "command": "python",
      "args": ["-m", "marqeta_diva_mcp.server"],
      "cwd": "/path/to/marqeta-diva-mcp",
      "env": {
        "MARQETA_APP_TOKEN": "your_application_token",
        "MARQETA_ACCESS_TOKEN": "your_access_token",
        "MARQETA_PROGRAM": "your_program_name"
      }
    }
  }
}

具有RAG功能（需要 pip install -e ".[rag]" 第一）：

{
  "mcpServers": {
    "marqeta-diva": {
      "command": "python",
      "args": ["-m", "marqeta_diva_mcp.server"],
      "cwd": "/path/to/marqeta-diva-mcp",
      "env": {
        "MARQETA_APP_TOKEN": "your_application_token",
        "MARQETA_ACCESS_TOKEN": "your_access_token",
        "MARQETA_PROGRAM": "your_program_name",
        "ENABLE_LOCAL_STORAGE": "true"
      }
    }
  }
}

平台集成

此MCP服务器可以与各种AI平台和工具集成。我们为以下方面提供全面的指南：

MCP兼容平台

• 克劳德桌面 （见上面的配置）-原生MCP支持
• 克劳德代码 -支持MCP的CLI
• 克莱恩 -支持MCP的VS代码扩展
• 其他MCP客户端 -任何支持MCP协议的客户端

非MCP平台

• ChatGPT/OpenAI -使用直接Python客户端、REST包装器或导出方法
• Jupyter笔记本 -通过pandas直接使用客户端
• Python脚本 -独立脚本集成
• 自定义应用程序 -REST API包装器、Slack/Discord机器人程序、web仪表板

集成指南

📚 集成.md -全面的集成指南涵盖：

• 每个平台的详细设置说明
• 配置示例和代码片段
• 故障排除提示
• 安全和性能的最佳实践
• 自定义集成模式

⚡ QUICK_INTEGRATION.md -快速参考指南，包括：

• 2分钟克劳德桌面设置
• 2分钟克劳德代码设置
• 1分钟Python/Jupyter设置
• 快速故障排除提示

可用工具

交易工具

get_authorizations

获取授权交易数据，包括金额、计数、代理用户/卡和商家信息。

参数：

• aggregation （字符串）： detail, day, week，或 month （默认值： detail)
• start_date （字符串）：ISO格式的开始日期（YYYY-MM-DD或YYYY-MM-MD-DTHH:MM:SS）
• end_date （字符串）：ISO格式的结束日期
• fields （array）：要返回的特定字段
• filters （对象）：附加过滤器（例如。， {"transaction_amount": ">100"})
• sort_by （string）：要排序的字段（前缀为 - 下降）
• count （整数）：要返回的最大记录数（最多10000条）
• program （string）：覆盖默认程序名

例子：

{
  "aggregation": "day",
  "start_date": "2024-01-01",
  "end_date": "2024-01-31",
  "filters": {"transaction_amount": ">1000"},
  "sort_by": "-request_amount",
  "count": 100
}

get_settlements

获取结算交易数据，包括状态、过账日期、购买金额和网络信息。

参数： 同 get_authorizations

get_clearings

获取交易生命周期的会计级别行项目。和解的理想选择。

参数： 同 get_authorizations

get_declines

获取被拒绝的交易数据，包括代币、拒绝原因、商家信息和金额。

参数： 同 get_authorizations

get_loads

获取负载交易数据，包括金额和交易详细信息。

参数： 同 get_authorizations

金融工具

get_program_balances

获取程序级余额数据，包括期初/期末银行余额和要发送/接收的金额。

参数：

• start_date, end_date, fields, filters, sort_by, count, program

get_program_balances_settlement

获取基于结算的程序余额数据和资金转账。

参数： 同 get_program_balances

get_activity_balances

获取持卡人级别的余额数据，可通过网络进行扩展。

参数：

• 所有标准参数加上：
• expand （string）：展开以获取更多详细信息的字段（例如，网络数据）

卡片和用户工具

get_cards

获取卡详细数据，包括用户令牌、卡状态、活动状态和UAI。

参数：

• fields, filters, sort_by, count, program

过滤器示例：

{
  "filters": {
    "state": "ACTIVE",
    "user_token": "abc123"
  }
}

get_users

获取用户详细数据，包括令牌、UAI和物理/虚拟卡的数量。

参数： 同 get_cards

退单工具

get_chargebacks_status

获取退款状态数据，包括状态、代币和临时信用状态。

参数：

• start_date, end_date, fields, filters, sort_by, count, program

get_chargebacks_detail

获取交易日期和类型的详细退款信息。

参数： 同 get_chargebacks_status

对账工具

get_transaction_token ⭐ v0.3.0中的新功能

对和解至关重要 -将核心API交易令牌映射到DiVA报告交易令牌。

目的： 将webhook交易数据链接到DiVA报告数据。对财务对账工作流程至关重要。

参数：

• fields, filters, sort_by, count, program

例子：

{
  "filters": {
    "core_api_transaction_token": "xyz123"
  }
}

监视工具

get_card_counts 📊 v0.3.0中的新功能

获取随时间汇总的卡数指标。跟踪卡在流通、活动、暂停等。

参数：

• aggregation （字符串）： day, week，或 month （必填，无详细级别）
• fields, filters, sort_by, count, program

例子：

{
  "aggregation": "day",
  "count": 30
}

get_user_counts 📊 v0.3.0中的新功能

获取随时间汇总的用户计数指标。跟踪用户群增长和参与度。

参数：

• aggregation （字符串）： day, week，或 month （必填，无详细级别）
• fields, filters, sort_by, count, program

例子：

{
  "aggregation": "week",
  "filters": {
    "user_type": "BUSINESS"
  }
}

网络分析工具

get_activity_balances_network_detail 🌐 v0.3.0中的新功能

获取按卡网络（Visa、Mastercard、Maestro、Cirrus等）划分的活动余额数据。

目的： 了解网络特定的交易量。仅限日聚合。

参数：

• fields, filters, sort_by, count, program
• expand （字符串）： pin_purchases_net 或 sig_purchases_net （逗号分隔为多个）

例子：

{
  "expand": "pin_purchases_net,sig_purchases_net",
  "count": 10
}

元数据工具

list_available_views

获取包含元数据的所有可用DiVA API视图端点的列表。

参数： 无

get_view_schema

获取具有字段名称、类型和描述的任何视图端点的架构定义。

参数：

• view_name （string，必填）：视图的名称（例如。， authorizations, settlements, cards)
• aggregation （string）：聚合级别（如果适用）（默认值： detail)

查询筛选

DiVA API支持强大的过滤运算符：

例子：

{
  "filters": {
    "transaction_amount": ">1000",
    "post_date": "2023-02-01..2023-02-28",
    "state": "COMPLETION"
  }
}

速率限制

• 最大值： 每5分钟间隔300个请求（≈每秒1个）
• 执行： 内置速率限制器自动限制请求
• 错误代码： 如果超过限制，则使用HTTP 429

数据同步

报告数据已同步 每日3次。有关具体的刷新时间表，请参阅Marqeta文档。

错误处理

服务器处理所有常见的DiVA API错误：

Claude使用示例

在Claude Desktop中配置后，您可以使用自然语言查询：

示例查询：

• “获取上周金额超过1000美元的所有授权交易”
• “显示2024年1月的结算数据”
• “列出用户令牌abc123的所有活动卡”
• “DiVA API中有哪些可用视图？”
• “获取结算视图的架构”
• “显示过去30天的退款状态”
• “获取2024年2月的计划余额”

API 文档

有关完整的DiVA API文件，请访问： https://www.marqeta.com/docs/diva-api/introduction/

故障排除

缺少凭据错误

Error: Missing required environment variables: MARQETA_APP_TOKEN, MARQETA_ACCESS_TOKEN, MARQETA_PROGRAM

解决方案： 确保您的 .env 文件存在，并包含所有三个必需的变量。

身份验证错误（403）

Error 403: Forbidden - Unauthorized access

解决方案： 验证您的应用程序令牌和访问令牌是否正确。检查您是否可以访问指定的程序。

速率限制错误（429）

Error 429: Rate limit exceeded - Maximum 300 requests per 5 minutes

解决方案： 内置的速率限制器应该可以防止这种情况，但如果你看到它，请等待几分钟再发出更多请求。

发展

运行测试

pytest

代码格式化

black src/
ruff check src/

贡献

欢迎投稿！请随时提交拉取请求。对于重大更改，请先打开一个问题来讨论您想要更改的内容。

开发设置

# Clone the repository
git clone https://github.com/zvika-finally/marqeta-diva-mcp.git
cd marqeta-diva-mcp

# Install with development dependencies
pip install -e ".[dev,rag]"

# Run tests
python test_fixes_unit.py

# Format code
black src/
ruff check src/

许可证

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

作者

兹维卡·巴达洛夫 - zvika.badalov@finally.com

致谢

• 内置于 模型上下文协议（MCP）
• 由...驱动 Marqeta的DiVA API

支持

• 问题：
• API Marqeta问题： 请联系您的Marqeta代表或参考 Marqeta官方文件

免责声明

这是一个非官方的社区项目，没有Marqeta，股份有限公司的官方认可或支持。使用风险自负。