# 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](https://github.com/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
```bash
cd execution/mcp-servers/minted
pip install -r requirements.txt
```
## Configuration
### Credentials
The server supports multiple authentication methods (checked in priority order):
1. **Environment Variables** (recommended, highest priority):
```bash
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):**
```json
{
"mcpServers": {
"minted": {
"command": "python3",
"args": [
"/path/to/minted_mcp_server.py"
],
"env": {
"MINTED_EMAIL": "your@email.com",
"MINTED_PASSWORD": "yourpassword"
}
}
}
}
```
**Option 2: Using 1Password integration (if parent repo structure exists):**
```json
{
"mcpServers": {
"minted": {
"command": "python3",
"args": [
"/path/to/minted_mcp_server.py"
],
"env": {}
}
}
}
```
**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):
```json
{
"mcpServers": {
"minted": {
"command": "python3",
"args": [
"/path/to/minted_mcp_server.py"
],
"env": {
"MINTED_EMAIL": "your@email.com",
"MINTED_PASSWORD": "yourpassword"
}
}
}
}
```
**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:**
```json
{
"success": true,
"count": 150,
"contacts": [
{
"id": 123,
"name": "John Doe",
"address1": "123 Main St",
"city": "San Francisco",
"state": "CA",
"zip": "94102"
}
]
}
```
### `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:**
```json
{
"success": true,
"delivery_date": "2025-12-15",
"order_id": "12345",
"status": "shipped",
"recipient_count": 25,
"recipients": [
{
"name": "Jane Smith",
"address1": "456 Oak Ave",
"city": "New York",
"state": "NY",
"zip": "10001"
}
]
}
```
### `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:**
```json
{
"success": true,
"count": 10,
"orders": [
{
"id": "12345",
"created_at": "2025-12-15",
"status": "shipped",
"total": 125.50
}
]
}
```
## 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](https://github.com/wkarney/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](https://github.com/markmhendrickson/mcp-server-minted/issues)
