AIVA MCP Server
Model Context Protocol server for AIVA - Connect your AI coding tools to AIVA's customer intelligence and Shopify data.
What is this?
AIVA MCP is a Model Context Protocol server that gives AI coding assistants (Claude, Cursor, Windsurf, etc.) direct access to:
- Customer Intelligence - RFM segments, health scores, churn predictions
- Subscription Data - Active subscriptions, delivery schedules, lifecycle events
- Affiliate Tracking - Referral codes, commissions, leaderboards
- Shopify Store Data - Products, orders, customers (proxied through AIVA)
Quick Start
Installation
npm install @getaiva/mcp
Configuration
Add to your MCP configuration file:
Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"aiva": {
"command": "npx",
"args": ["@getaiva/mcp"],
"env": {
"AIVA_API_KEY": "your-api-key-here"
}
}
}
}
Cursor (.cursor/mcp.json in your project):
{
"mcpServers": {
"aiva": {
"command": "npx",
"args": ["@getaiva/mcp"],
"env": {
"AIVA_API_KEY": "your-api-key-here"
}
}
}
}
VS Code with Continue (.continue/config.json):
{
"mcpServers": [
{
"name": "aiva",
"command": "npx",
"args": ["@getaiva/mcp"],
"env": {
"AIVA_API_KEY": "your-api-key-here"
}
}
]
}
Getting Your API Key
- Log in to your AIVA Merchant Dashboard
- Go to Settings > API Keys
- Create a new API key with the scopes you need
- Copy the key and add it to your MCP configuration
Available Tools
Once connected, your AI assistant can use these tools:
Customer Intelligence
| Tool | Description |
|---|---|
aiva_get_customer | Get customer profile by ID or email |
aiva_search_customers | Search customers with filters |
aiva_get_rfm_segments | Get RFM segment breakdown |
aiva_get_churn_risk | Get customers at risk of churning |
Subscriptions
| Tool | Description |
|---|---|
aiva_get_subscription | Get subscription details |
aiva_list_subscriptions | List subscriptions with filters |
aiva_get_delivery_schedule | Get upcoming deliveries |
aiva_subscription_actions | Pause, resume, skip, swap products |
Affiliates
| Tool | Description |
|---|---|
aiva_get_affiliate | Get affiliate details |
aiva_list_affiliates | List affiliates with stats |
aiva_get_referrals | Get referral history |
Shopify (Proxied)
| Tool | Description |
|---|---|
shopify_get_products | Search/list products |
shopify_get_product | Get product by ID |
shopify_get_orders | List orders |
shopify_get_customer | Get Shopify customer |
Environment Variables
| Variable | Required | Description |
|---|---|---|
AIVA_API_KEY | Yes | Your AIVA API key |
AIVA_API_URL | No | Custom API URL (default: https://api.aiva.io) |
SHOPIFY_ACCESS_TOKEN | No | Direct Shopify access (bypasses proxy) |
SHOPIFY_STORE | No | Your Shopify store domain |
Example Usage
Once configured, ask your AI assistant things like:
"Show me customers at high risk of churning"
"Get the subscription details for customer john@example.com"
"List all products in the 'dog-food' collection"
"What are our top-performing affiliates this month?"
"Find customers in the 'Champions' RFM segment"
Development
Running Locally
git clone https://github.com/0800tim/aiva-mcp.git
cd aiva-mcp
npm install
npm run dev
Testing
npm test
Building
npm run build
Troubleshooting
"AIVA_API_KEY not configured"
Make sure your API key is set in the env section of your MCP configuration.
"Connection refused"
Check that:
- Your API key is valid
- You have network access to the AIVA API
- The MCP server started correctly
Debug Mode
Set DEBUG=aiva:* environment variable for verbose logging:
{
"env": {
"AIVA_API_KEY": "your-key",
"DEBUG": "aiva:*"
}
}
Related Packages
@getaiva/create-app- CLI to scaffold AIVA-powered appscustomer-portal-starter- Customer portal starter kit
License
MIT - see LICENSE for details.