Skip to main content
Glama
Marqeta DiVA API MCP Server

Marqeta DiVA API MCP Server

by tbadlov

Marqeta DiVA API MCP Server

PyPI version Python 3.10+ License: MIT

A Model Context Protocol (MCP) server that provides programmatic access to the Marqeta DiVA (Data insights, Visualization, and Analytics) API. This server enables AI assistants and applications to retrieve aggregated production data from the Marqeta platform for reporting, analytics, and data-driven business decisions.

Note: This is an unofficial community project and is not officially supported by Marqeta.

Features

Core Features (Always Available)

  • Transaction Data: Access authorizations, settlements, clearings, declines, and loads

  • Financial Data: Retrieve program balances, settlement balances, and activity balances

  • Card & User Data: Get card and user details with flexible filtering

  • Chargeback Data: Access chargeback status and detailed information

  • Metadata Tools: Discover available views and retrieve schema definitions

  • Export Tools: Export data to JSON or CSV files

  • Rate Limiting: Built-in rate limiting to comply with API limits (300 requests per 5 minutes)

  • Error Handling: Comprehensive error handling with meaningful messages

  • Flexible Querying: Support for filtering, sorting, field selection, date ranges, and more

Optional RAG Features (Requires [rag] extras)

  • Local Storage: Store complete transaction data in SQLite (bypasses MCP token limits)

  • Semantic Search: Natural language queries on transaction data using AI embeddings

  • Vector Store: ChromaDB integration for similarity-based transaction search

  • Offline Analysis: Query local data without API calls or token limits

Related MCP server: netsuite-saved-search-mcp

Prerequisites

  • Python 3.10 or higher

  • uv package manager (for running with uvx)

  • Marqeta DiVA API credentials (Application Token, Access Token, and Program Name)

Installation

No installation needed! uvx will automatically handle dependencies when you run the server.

For basic features only:

uvx marqeta-diva-mcp

For RAG features (local storage + semantic search):

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

Option 2: Traditional Installation

Basic installation (core features only):

pip install marqeta-diva-mcp

With RAG features (recommended for advanced analytics):

pip install marqeta-diva-mcp[rag]

From source:

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

Configuration

  1. Copy the example environment file:

cp .env.example .env
  1. Edit .env and add your Marqeta DiVA API credentials:

# 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

How to obtain credentials:

  • Contact your Marqeta representative, OR

  • Generate via Marqeta Dashboard (Reports section)

Enabling RAG Features:

To use local storage, semantic search, and other RAG features:

  1. Install RAG dependencies: pip install marqeta-diva-mcp[rag]

  2. Set environment variable: ENABLE_LOCAL_STORAGE=true

  3. Restart the MCP server

When enabled, you'll see this message in the logs:

[MCP Server] Local storage and RAG features ENABLED

When disabled (default):

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

Usage

Running the Server Locally

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

With Python

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

Adding to Claude Desktop

Add this configuration to your Claude Desktop config file:

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

Basic configuration (core features only):

{
  "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"
      }
    }
  }
}

With RAG features (local storage + semantic search):

{
  "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"
      }
    }
  }
}

Using Python

Basic configuration (core features only):

{
  "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"
      }
    }
  }
}

With RAG features (requires pip install -e ".[rag]" first):

{
  "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"
      }
    }
  }
}

Platform Integrations

This MCP server can be integrated with various AI platforms and tools. We provide comprehensive guides for:

MCP-Compatible Platforms

  • Claude Desktop (see configuration above) - Native MCP support

  • Claude Code - CLI with MCP support

  • Cline - VS Code extension with MCP support

  • Other MCP clients - Any client supporting the MCP protocol

Non-MCP Platforms

  • ChatGPT / OpenAI - Using direct Python client, REST wrapper, or export methods

  • Jupyter Notebooks - Direct client usage with pandas

  • Python Scripts - Standalone script integration

  • Custom Applications - REST API wrappers, Slack/Discord bots, web dashboards

Integration Guides

📚 INTEGRATIONS.md - Comprehensive integration guide covering:

  • Detailed setup instructions for each platform

  • Configuration examples and code snippets

  • Troubleshooting tips

  • Best practices for security and performance

  • Custom integration patterns

⚡ QUICK_INTEGRATION.md - Quick reference guide with:

  • 2-minute Claude Desktop setup

  • 2-minute Claude Code setup

  • 1-minute Python/Jupyter setup

  • Fast troubleshooting tips

Available Tools

Transaction Tools

get_authorizations

Get authorization transaction data with amounts, counts, acting users/cards, and merchant information.

Parameters:

  • aggregation (string): detail, day, week, or month (default: detail)

  • start_date (string): Start date in ISO format (YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS)

  • end_date (string): End date in ISO format

  • fields (array): Specific fields to return

  • filters (object): Additional filters (e.g., {"transaction_amount": ">100"})

  • sort_by (string): Field to sort by (prefix with - for descending)

  • count (integer): Maximum records to return (up to 10,000)

  • program (string): Override default program name

Example:

{
  "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 settlement transaction data including status, post dates, purchase amounts, and network information.

Parameters: Same as get_authorizations

get_clearings

Get accounting-level line items for transaction lifecycle. Ideal for reconciliation.

Parameters: Same as get_authorizations

get_declines

Get declined transaction data with tokens, decline reasons, merchant info, and amounts.

Parameters: Same as get_authorizations

get_loads

Get load transaction data including amounts and transaction details.

Parameters: Same as get_authorizations

Financial Tools

get_program_balances

Get program-level balance data including beginning/ending bank balances and amounts to send/receive.

Parameters:

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

get_program_balances_settlement

Get settlement-based program balance data and fund transfers.

Parameters: Same as get_program_balances

get_activity_balances

Get cardholder-level balance data, expandable by network.

Parameters:

  • All standard parameters plus:

  • expand (string): Field to expand for more detail (e.g., network data)

Card & User Tools

get_cards

Get card detail data including user tokens, card state, active status, and UAI.

Parameters:

  • fields, filters, sort_by, count, program

Example filters:

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

get_users

Get user detail data including tokens, UAI, and number of physical/virtual cards.

Parameters: Same as get_cards

Chargeback Tools

get_chargebacks_status

Get chargeback status data including state, tokens, and provisional credit status.

Parameters:

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

get_chargebacks_detail

Get detailed chargeback information with transaction dates and types.

Parameters: Same as get_chargebacks_status

Reconciliation Tools

get_transaction_token ⭐ NEW in v0.3.0

CRITICAL for reconciliation - Map Core API transaction tokens to DiVA report transaction tokens.

Purpose: Links webhook transaction data to DiVA reporting data. Essential for financial reconciliation workflows.

Parameters:

  • fields, filters, sort_by, count, program

Example:

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

Monitoring Tools

get_card_counts 📊 NEW in v0.3.0

Get card count metrics aggregated over time. Track cards in circulation, active, suspended, etc.

Parameters:

  • aggregation (string): day, week, or month (required, no detail level)

  • fields, filters, sort_by, count, program

Example:

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

get_user_counts 📊 NEW in v0.3.0

Get user count metrics aggregated over time. Track user base growth and engagement.

Parameters:

  • aggregation (string): day, week, or month (required, no detail level)

  • fields, filters, sort_by, count, program

Example:

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

Network Analytics Tools

get_activity_balances_network_detail 🌐 NEW in v0.3.0

Get activity balance data broken out by card network (Visa, Mastercard, Maestro, Cirrus, etc.).

Purpose: Understand network-specific transaction volumes. Day aggregation only.

Parameters:

  • fields, filters, sort_by, count, program

  • expand (string): pin_purchases_net or sig_purchases_net (comma-delimited for multiple)

Example:

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

Metadata Tools

list_available_views

Get a list of all available DiVA API view endpoints with metadata.

Parameters: None

get_view_schema

Get the schema definition for any view endpoint with field names, types, and descriptions.

Parameters:

  • view_name (string, required): Name of the view (e.g., authorizations, settlements, cards)

  • aggregation (string): Aggregation level if applicable (default: detail)

Query Filtering

The DiVA API supports powerful filtering operators:

Operator

Description

Example

~

Like (wildcard)

{"company": "Mar~eta"}

..

Range

{"date": "2023-10-01..2023-10-03"}

<, <=

Less than

{"amount": "<=100"}

>, >=

Greater than

{"date": ">=2023-04-01"}

=

Equal/In list

{"amount": "0"} or {"country": "United States,Mexico"}

=!

Not equal/Not in

{"amount": "=!0"}

Example:

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

Rate Limits

  • Maximum: 300 requests per 5-minute interval (≈1 per second)

  • Enforcement: Built-in rate limiter automatically throttles requests

  • Error Code: HTTP 429 if limit exceeded

Data Synchronization

Report data is synchronized 3 times daily. See Marqeta documentation for specific refresh timelines.

Error Handling

The server handles all common DiVA API errors:

Code

Description

400

Bad Request - Malformed query or filter

403

Forbidden - Unauthorized access to field, filter, or program

404

Not Found - Malformed URL or endpoint doesn't exist

429

Rate limit exceeded

Example Usage with Claude

Once configured in Claude Desktop, you can use natural language queries:

Example queries:

  • "Get all authorization transactions from last week with amounts over $1000"

  • "Show me the settlement data for January 2024"

  • "List all active cards for user token abc123"

  • "What are the available views in the DiVA API?"

  • "Get the schema for the settlements view"

  • "Show me chargeback status for the last 30 days"

  • "Get program balances for February 2024"

API Documentation

For complete DiVA API documentation, visit: https://www.marqeta.com/docs/diva-api/introduction/

Troubleshooting

Missing Credentials Error

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

Solution: Ensure your .env file exists and contains all three required variables.

Authentication Error (403)

Error 403: Forbidden - Unauthorized access

Solution: Verify your Application Token and Access Token are correct. Check that you have access to the specified program.

Rate Limit Error (429)

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

Solution: The built-in rate limiter should prevent this, but if you see it, wait a few minutes before making more requests.

Development

Running Tests

pytest

Code Formatting

black src/
ruff check src/

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Development Setup

# 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/

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

Zvika Badalov - zvika.badalov@finally.com

Acknowledgments

Support

Disclaimer

This is an unofficial community project and is not officially endorsed or supported by Marqeta, Inc. Use at your own risk.

Available Tools

20 tools
export_view_to_fileA

Export datasets to a file (JSON or CSV). Note: DiVA API limits results to 10,000 records per query. To get more data, use narrower date ranges or more specific filters and call multiple times. Supports all view types: authorizations, settlements, clearings, declines, loads, cards, users, etc.

Inputs: view_name (required), output_path (required), aggregation, format, +5 more.

get_activity_balancesB

Get cardholder-level balance data. Includes individual cardholder balances, expandable by network. Day-level aggregation only.

Inputs: fields, filters, sort_by, count, +2 more.

get_activity_balances_network_detailA

Get activity balance data broken out by card network (Visa, Mastercard, Maestro, Cirrus, etc.). Includes PIN and signature purchases by network. Day aggregation only. Use 'expand' parameter to break out specific transaction types by network. Essential for understanding network-specific transaction volumes.

Inputs: fields, filters, sort_by, count, +2 more.

get_authorizationsA

Get authorization transaction data. Includes authorization amounts, counts, acting users/cards, and merchant information. Supports detail, day, week, and month aggregation. Note: DiVA API limits results to 10,000 records per query. Use narrower date ranges or more specific filters for larger datasets.

Inputs: aggregation, fields, filters, sort_by, +2 more.

get_card_countsB

Get card count metrics aggregated over time. Track cards in circulation, active cards, suspended cards, and more. Essential for program health monitoring. Supports day, week, and month aggregation. Note: DiVA API limits results to 10,000 records per query.

Inputs: aggregation, fields, filters, sort_by, +2 more.

get_cardsA

Get card detail data. Includes user tokens, card state, active status, and UAI. Detail-level only. Supports filtering by user, state, etc. Note: DiVA API limits results to 10,000 records per query. Use narrower date ranges or more specific filters for larger datasets.

Inputs: fields, filters, sort_by, count, +1 more.

get_chargebacks_detailC

Get detailed chargeback information. Includes transaction dates/types and comprehensive chargeback details.

Inputs: fields, filters, sort_by, count, +1 more.

get_chargebacks_statusB

Get chargeback status data. Includes chargeback state, tokens, and provisional credit status.

Inputs: fields, filters, sort_by, count, +1 more.

get_clearingsA

Get clearing/reconciliation data. Provides accounting-level line items for the transaction lifecycle. Ideal for reconciliation. Supports detail, day, week, and month aggregation. Note: DiVA API limits results to 10,000 records per query. Use narrower date ranges or more specific filters for larger datasets.

Inputs: aggregation, fields, filters, sort_by, +2 more.

get_declinesA

Get declined transaction data. Includes transaction tokens, decline reasons, merchant information, and amounts. Supports detail, day, week, and month aggregation. Note: DiVA API limits results to 10,000 records per query. Use narrower date ranges or more specific filters for larger datasets.

Inputs: aggregation, fields, filters, sort_by, +2 more.

get_loadsB

Get load transaction data. Includes load amounts and transaction details. Note: DiVA API limits results to 10,000 records per query. Use narrower date ranges or more specific filters for larger datasets.

Inputs: aggregation, fields, filters, sort_by, +2 more.

get_program_balancesA

Get program-level balance data. Includes beginning/ending bank balances, amounts to send/receive. Day-level aggregation only.

Inputs: fields, filters, sort_by, count, +1 more.

get_program_balances_settlementA

Get settlement-based program balance data. Includes settlement balance information and fund transfers. Day-level aggregation only.

Inputs: fields, filters, sort_by, count, +1 more.

get_server_versionA

Get the MCP server version to verify it has been restarted with latest code changes.

Inputs: no named parameters.

get_settlementsA

Get settlement transaction data. Includes transaction status, post dates, purchase amounts, and network information. Supports detail, day, week, and month aggregation. Note: DiVA API limits results to 10,000 records per query. Use narrower date ranges or more specific filters for larger datasets.

Inputs: aggregation, fields, filters, sort_by, +2 more.

get_transaction_tokenA

Map Core API transaction tokens to DiVA report transaction tokens. CRITICAL for reconciliation workflows - links webhook transaction data to DiVA reports. Use this to reconcile transactions between Core API (webhooks) and DiVA reporting data.

Inputs: fields, filters, sort_by, count, +1 more.

get_user_countsB

Get user count metrics aggregated over time. Track users with accounts, suspended users, and user growth. Essential for program monitoring and analytics. Supports day, week, and month aggregation. Note: DiVA API limits results to 10,000 records per query.

Inputs: aggregation, fields, filters, sort_by, +2 more.

get_usersA

Get user detail data. Includes user tokens, UAI, and number of physical/virtual cards. Detail-level only. Note: DiVA API limits results to 10,000 records per query. Use more specific filters for larger datasets.

Inputs: fields, filters, sort_by, count, +1 more.

get_view_schemaA

Get the schema definition for any view endpoint. Returns field names, data types, and descriptions.

Inputs: view_name (required), aggregation.

list_available_viewsA

Get a list of all available DiVA API view endpoints with metadata. Useful for discovering available data sources.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 20 tools

    Disambiguation5/5

    Each tool targets a distinct data type or aggregation level (authorizations, settlements, declines, balances, counts, etc.) with clear descriptions. Even related tools like get_chargebacks_detail and get_chargebacks_status serve clearly different purposes (detail vs status). No overlapping ambiguity.

    Naming Consistency4/5

    Most tools follow a 'get_' prefix with a noun describing the data (e.g., get_authorizations). Two exceptions: export_view_to_file and list_available_views use different verbs, but these are distinct actions (export vs list) and still clear. Overall pattern is consistent and readable.

    Tool Count5/5

    20 tools is well-scoped for a financial reporting API. Each tool corresponds to a specific endpoint or metric, and the count covers the full range of DiVA views without unnecessary duplication. It's not too heavy nor too thin.

    Completeness4/5

    The tool set covers the major reporting areas: authorizations, settlements, declines, chargebacks, balances, cards, users, counts, and export. Minor gaps exist (e.g., no refunds or dispute tools), but for a typical reporting use case, the coverage is thorough and no critical dead ends are apparent.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Exposes NetSuite saved search exports as a structured query interface for Claude, enabling file discovery, column inspection, filtering, aggregation, memo categorization, and anomaly detection.
      7
      MIT
    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to retrieve and analyze Dwolla payment platform data using natural language, with read-only access to accounts, transfers, customers, and compliance information.
      53 npm
      3
      -
    • A
      license
      B
      quality
      F
      maintenance
      Query bank accounts, credit cards, and transactions via Sophtron's financial data API. Works with Claude Desktop and any MCP-compatible client.
      10
      1
      Apache 2.0