# mParticle MCP Server

A Model Context Protocol (MCP) server that provides integration with mParticle's Data Planning API. This server allows Claude Desktop and other MCP-compatible clients to interact with your mParticle data plans, retrieve schemas, and manage data governance workflows.

## 🚀 Features

- **Data Plan Management**: Retrieve all data plans or specific data plans by plan ID from your mParticle workspace
- **Authentication**: Secure authentication with mParticle's API using client credentials stored as environment variables
- **Automatic Token Management**: Handles bearer token refresh and expiration automatically
- **MCP Standard**: Built using FastMCP framework for integration with Claude Desktop or other MCP clients.

## 📋 Available Tools

### `get_all_data_plans`
Retrieves all data plans for a specified workspace, including metadata like creation dates, descriptions, and plan status.

**Parameters:**
- `workspace_id` (string): The mParticle workspace ID (required)

### `get_data_plan_by_id`
Retrieves detailed information about a specific data plan, including version information and data plan elements.

**Parameters:**
- `workspace_id` (string): The mParticle workspace ID (required)  
- `data_plan_id` (string): The data plan ID to retrieve (required)

### `get_api_status`
Checks the configuration status of the mParticle API client and credentials.

## 🛠️ Installation

### Prerequisites

- **Python 3.12+**: Ensure you have Python 3.12 or higher installed
- **Claude Desktop**: Download and install from the [official website](https://claude.ai/download)
- **mParticle API Credentials**: You'll need an API key and secret from your mParticle account

### 1. Clone and Setup the Project

```bash
git clone <repository-url>
cd mparticle_mcp_server

# Install dependencies using uv (recommended)
uv sync

# Or install using pip
pip install -e .
```

### 2. Environment Configuration

Create a `.env` file in the project root or set environment variables:

```bash
export MPARTICLE_API_KEY="your_mparticle_api_key"
export MPARTICLE_API_SECRET="your_mparticle_api_secret"
```

**Getting mParticle API Credentials:**
1. Log into your mParticle dashboard
2. Navigate to Settings > Setup > API Keys
3. Create a new API key with Data Planning permissions
4. Copy the Key ID (API Key) and Secret

### 3. Test the Server

Run the server directly to test the configuration:

```bash
python mp_data_plan.py
```

If configured correctly, you should see:
```
✅ mParticle API client configured and ready
🚀 Starting MCP server...
```

## 🔧 Claude Desktop Integration

To use this MCP server with Claude Desktop, you need to add it to your Claude Desktop configuration.

### Configuration File Location

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`

### Configuration Setup

1. **Locate or create the configuration file** at the path above for your operating system.

2. **Add the MCP server configuration**:

```json
{
  "mcpServers": {
    "mparticle": {
      "command": "uv",
      "args": [
        "run", 
        "python", 
        "/Users/nmattox/Documents/Apps & Scripts/gen_ai/mparticle_mcp_server/mp_data_plan.py"
      ],
      "env": {
        "MPARTICLE_API_KEY": "your_mparticle_api_key",
        "MPARTICLE_API_SECRET": "your_mparticle_api_secret"
      }
    }
  }
}
```

**Important Notes:**
- Replace the path in `args` with the absolute path to your `mp_data_plan.py` file
- Replace the environment variables with your actual mParticle API credentials
- If you don't use `uv`, you can replace `"command": "uv"` with `"command": "python"` and adjust the args accordingly:

```json
{
  "mcpServers": {
    "mparticle": {
      "command": "python",
      "args": [
        "/Users/nmattox/Documents/Apps & Scripts/gen_ai/mparticle_mcp_server/mp_data_plan.py"
      ],
      "env": {
        "MPARTICLE_API_KEY": "your_mparticle_api_key", 
        "MPARTICLE_API_SECRET": "your_mparticle_api_secret"
      }
    }
  }
}
```

3. **Restart Claude Desktop** after saving the configuration file.

4. **Verify the installation**:
   - Open Claude Desktop
   - Look for the 🔌 plug icon next to the message input
   - Click it to see available MCP tools - you should see the mParticle tools listed

## 💡 Usage Examples

Once integrated with Claude Desktop, you can use natural language to interact with your mParticle data:

### Example Queries:

**"Show me all data plans in workspace 12345 - provide summaries for each plan"**
- Claude will use the `get_all_data_plans` tool automatically to pull all data plans then create a summary 

**"Get details for data plan 'mobile-app-schema' in workspace 12345 - share a summary of all data elements and suggest possible mParticle use cases given the plan"**  
- Claude will use the `get_data_plan_by_id` tool to pull the specific data plan, create a plan summary, then suggest possible use cases. 

**"Check if mParticle API is configured properly"**
- Claude will use the `get_api_status` tool

**"Given my use case XYZ and data plan xyz-789 for workspace 12345 - what are suggested improvements I can make to the data plan?"**
- Claude will retrieve the data plan and suggest plan improvements given the use case 

## 🏗️ Project Structure

```
mparticle_mcp_server/
├── mp_data_plan.py       # Main MCP server with FastMCP tools
├── mparticle_api.py      # mParticle API client and authentication
├── main.py               # Simple test entry point
├── pyproject.toml        # Project dependencies and metadata
├── uv.lock              # Locked dependencies
└── README.md            # This file
```

## 🔗 Related Links

- [mParticle API Documentation](https://docs.mparticle.com/developers/server/http/)
- [Model Context Protocol Specification](https://modelcontextprotocol.io/introduction)
- [Claude Desktop](https://claude.ai/download)
- [FastMCP Framework](https://github.com/jlowin/fastmcp)