AIVA MCP Server

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

Subscriptions

Affiliates

Shopify (Proxied)

Environment Variables

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