# @walletap/mcp-server

Issue and manage Apple Wallet & Google Wallet passes from any AI assistant.

## Quick Start

```bash
npx @walletap/mcp-server
```

Or install globally:

```bash
npm install -g @walletap/mcp-server
walletap-mcp
```

## Authentication

Set your Walletap API key as an environment variable:

```bash
export WALLETAP_API_KEY=wt_live_xxxxxxxxxxxxxxxxxxxx
```

You can find your API key in the [Walletap dashboard](https://app.walletap.io) under Settings.

## Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "walletap": {
      "command": "npx",
      "args": ["-y", "@walletap/mcp-server"],
      "env": {
        "WALLETAP_API_KEY": "wt_live_xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

## Cursor / Windsurf

Add to `.cursor/mcp.json` or `.windsurf/mcp.json`:

```json
{
  "mcpServers": {
    "walletap": {
      "command": "npx",
      "args": ["-y", "@walletap/mcp-server"],
      "env": {
        "WALLETAP_API_KEY": "wt_live_xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

## HTTP Remote Mode

For self-hosted deployments, n8n, Make, or Zapier AI:

```bash
walletap-mcp --transport http
```

This starts an HTTP server (default port 3001) exposing:
- `POST /mcp` — JSON-RPC endpoint
- `GET /mcp/sse` — Server-Sent Events for streaming
- `GET /health` — Health check

Docker example:

```dockerfile
FROM node:22-alpine
RUN npm install -g @walletap/mcp-server
ENV WALLETAP_API_KEY=wt_live_xxxxxxxxxxxxxxxxxxxx
ENV MCP_PORT=3001
EXPOSE 3001
CMD ["walletap-mcp", "--transport", "http"]
```

## Tools Reference

| Tool | What it does | Key inputs |
|------|-------------|------------|
| `list_passes` | List passes for a template with pagination | `templateId`, `status`, `limit` |
| `search_passes` | Search passes by email or phone | `templateId`, `searchQuery` |
| `export_passes` | Export passes as CSV | `templateId`, `status` |
| `get_pass` | Get a single pass with wallet URLs | `id` or `externalId`+`templateId` |
| `create_pass` | Create one or more wallet passes | `passes[]`, `sendToEmail`, `sendToPhone` |
| `update_pass` | Update pass fields, stamps, or balance | `id`, `templateFields`, `stampOperation`, `balanceOperation` |
| `notify_pass` | Send notification to one pass holder | `passId`, `title`, `content` |
| `list_templates` | List all pass templates | `limit`, `startAfter` |
| `create_template` | Create a new template | `name`, `type` |
| `update_template` | Update template config/design | `templateId`, `data` |
| `delete_template` | Delete a template | `templateId` |
| `send_template_notification` | Notify all pass holders in a template | `templateId`, `title`, `content` |
| `create_certificate` | Create Apple Wallet certificate | `templateId` |
| `list_locations` | List all business locations | — |
| `create_location` | Create a new location | `name`, `latitude`, `longitude` |
| `update_location` | Update location details | `id`, `name`, `address` |
| `delete_location` | Delete a location | `id` |
| `create_reader` | Create a VTAP NFC reader | `name`, `templateId`, `phone` |
| `list_sub_accounts` | List team members | — |
| `create_sub_account` | Create a team member | `email`, `displayName`, `password` |
| `update_sub_account` | Update team member permissions | `userId`, `permissions`, `templateIds` |
| `delete_sub_account` | Remove a team member | `userId` |
| `translate_pass_text` | Translate pass text to multiple languages | `texts`, `sourceLanguage`, `targetLanguages` |

## Example Prompts

Here are things you can say to your AI assistant with Walletap connected:

- **"Create a loyalty card template called 'Coffee Rewards' and issue a pass to john@example.com"**
- **"Show me all passes for my loyalty template that haven't been installed yet"**
- **"Add 3 stamps to the pass with external ID 'CUST-42' in my stamp card template"**
- **"Send a notification to all pass holders: 'Double points this weekend! Visit any location to earn 2x.'"**
- **"Export all my loyalty passes as CSV for the marketing team"**
- **"Translate our pass labels into Spanish, French, and German"**

## API Base URL

By default connects to `https://api.walletap.io`. Override with:

```bash
export WALLETAP_API_BASE_URL=https://your-custom-instance.example.com
```

## License

MIT