Marqeta DiVA API MCP Server
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
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
Option 1: Run with uvx (Recommended)
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
- Copy the example environment file:
cp .env.example .env
- Edit
.envand 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:
- Install RAG dependencies:
pip install marqeta-diva-mcp[rag] - Set environment variable:
ENABLE_LOCAL_STORAGE=true - 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
With uvx (Recommended)
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
Using uvx (Recommended)
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, ormonth(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 formatfields(array): Specific fields to returnfilters(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, ormonth(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, ormonth(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,programexpand(string):pin_purchases_netorsig_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
- Built with Model Context Protocol (MCP)
- Powered by Marqeta's DiVA API
Support
- Issues: GitHub Issues
- Marqeta API Questions: Contact your Marqeta representative or refer to the official Marqeta documentation
Disclaimer
This is an unofficial community project and is not officially endorsed or supported by Marqeta, Inc. Use at your own risk.