Minted MCP Server

MCP server for interacting with Minted.com API - address book, orders, and delivery information.

Credits

This MCP server is based on the authentication pattern from wkarney/minted-export, a utility to export addresses from minted.com. The original repository provided the Selenium-based authentication approach that this MCP server adapts for Model Context Protocol integration.

Features

• Get Contacts: Retrieve all contacts from Minted address book

• Get Latest Delivery: Get recipients from the most recent card delivery/order

• Get Orders: Get order history from Minted

Installation

Configuration

Credentials

The server supports multiple authentication methods (checked in priority order):

1. Environment Variables (recommended, highest priority):

   export MINTED_EMAIL="your@email.com" export MINTED_PASSWORD="yourpassword"

   Also supports lowercase: minted_email and minted_password

2. 1Password Integration (optional, for backward compatibility):

   • Only available if parent repository structure exists

   • Configure 1Password item with URL "minted.com"

   • Add fields: "email" and "password"

Note: The MCP server is self-contained and portable. It does not require any specific repository structure and can be used in any project.

Cursor Configuration

Add to your Cursor MCP settings (typically ~/.cursor/mcp.json or Cursor settings):

Option 1: Using environment variables (recommended):

Option 2: Using 1Password integration (if parent repo structure exists):

Note: Replace /path/to/minted_mcp_server.py with the actual path to the server file.

Claude Desktop Configuration

Add to claude_desktop_config.json (typically ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

Note: Replace /path/to/minted_mcp_server.py with the actual path to the server file.

Available Tools

get_minted_contacts

Get all contacts from Minted address book.

Returns:

• count: Number of contacts

• contacts: Array of contact objects with name, address, etc.

Example:

get_minted_latest_delivery

Get recipients from the latest Minted card delivery/order.

Returns:

• delivery_date: Date of the delivery

• order_id: Order identifier

• status: Delivery status

• recipient_count: Number of recipients

• recipients: Array of recipient objects

• raw_delivery_data: Complete delivery data structure

Example:

get_minted_orders

Get order history from Minted.

Parameters:

• limit (optional): Maximum number of orders to return (default: 10)

Returns:

• count: Number of orders returned

• orders: Array of order objects

Example:

Authentication

The server uses Selenium to authenticate with Minted.com and then uses session cookies for API requests. This matches the authentication pattern used in the original minted-export scripts.

Note: Authentication happens on first API call and cookies are cached for subsequent calls in the same session.

Error Handling

The server returns structured error messages in JSON format when operations fail. Common errors include:

• Credential errors (missing email/password)

• Authentication failures

• API endpoint not found

• Network timeouts

Security Notes

• Credentials are never logged or exposed

• Session cookies are stored in memory only

• All network requests are to minted.com domains only

• Use 1Password integration for secure credential management

Troubleshooting

1. Authentication Fails

   • Verify credentials are correct

   • Check if Minted.com login page structure has changed

   • Try running scripts/export_minted_contacts.py manually to test authentication

2. API Endpoints Not Found

   • Minted API structure may have changed

   • Check browser Network tab when accessing Minted manually

   • Update endpoints in minted_mcp_server.py if needed

3. Selenium Issues

   • Ensure Chrome/Chromium is installed

   • webdriver-manager will download ChromeDriver automatically

   • For headless issues, try removing --headless flag temporarily

Notes

• The server uses headless Chrome via Selenium for authentication

• Session cookies are cached in memory for the duration of the server process

• All date fields are returned as strings in ISO format

• The server runs in stdio mode for MCP communication

License

MIT

Support

• GitHub Issues