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

1. Log in to your AIVA Merchant Dashboard
2. Go to Settings > API Keys
3. Create a new API key with the scopes you need
4. 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:

1. Your API key is valid
2. You have network access to the AIVA API
3. 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 apps
• customer-portal-starter - Customer portal starter kit

License

MIT - see LICENSE for details.

Support

• Documentation
• GitHub Issues
• Discord Community