# Jampp MCP Server

This MCP server provides access to the Jampp Reporting API through the Model Context Protocol, allowing LLMs to fetch campaign performance data.

## Features

- OAuth 2.0 authentication with automatic token refresh
- GraphQL-based API integration
- Campaign spend reporting
- Daily spend tracking
- Comprehensive performance metrics
- Asynchronous report generation and retrieval
- Available metrics and dimensions listing

## Prerequisites

- Python 3.10 or higher
- Jampp API credentials (Client ID and Client Secret)

## Installation

1. Clone this repository:
   ```bash
   git clone https://github.com/yourusername/mcp-jampp.git
   cd mcp-jampp
   ```

2. Install dependencies:
   ```bash
   uv add "mcp[cli]" httpx python-dotenv
   ```

   Or with pip:
   ```bash
   pip install "mcp[cli]" httpx python-dotenv
   ```

3. Set up your environment variables:
   Create a `.env` file in the project root with your Jampp API credentials:
   ```
   JAMPP_CLIENT_ID=your_client_id
   JAMPP_CLIENT_SECRET=your_client_secret
   ```

## Usage

### Running the Server Directly

```bash
python jampp_mcp_server.py
```

### Using with MCP Inspector

For development and testing:

```bash
mcp dev jampp_mcp_server.py
```

### Integration with Claude Desktop

1. Install Claude Desktop from [claude.ai/download](https://claude.ai/download)

2. Configure Claude Desktop to use this server:
   - Open or create `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows)
   - Add the following configuration:

   ```json
   {
     "mcpServers": {
       "jampp": {
         "command": "python",
         "args": ["path/to/jampp_mcp_server.py"],
         "env": {
           "JAMPP_CLIENT_ID": "your_client_id",
           "JAMPP_CLIENT_SECRET": "your_client_secret"
         }
       }
     }
   }
   ```

3. Restart Claude Desktop

## Available Tools

### 1. `get_campaign_spend`
Fetches campaign spend data for a specific date range.

**Parameters:**
- `from_date`: Start date in YYYY-MM-DD format
- `to_date`: End date in YYYY-MM-DD format
- `campaign_id` (optional): ID of the specific campaign to query

### 2. `get_campaign_daily_spend`
Fetches daily spend data for a specific campaign.

**Parameters:**
- `from_date`: Start date in YYYY-MM-DD format
- `to_date`: End date in YYYY-MM-DD format
- `campaign_id`: ID of the campaign to query
- `timezone` (optional): Timezone for the report (default: UTC)

### 3. `get_campaign_performance`
Fetches comprehensive performance metrics for campaigns.

**Parameters:**
- `from_date`: Start date in YYYY-MM-DD format
- `to_date`: End date in YYYY-MM-DD format
- `campaign_id` (optional): ID of a specific campaign to query
- `timezone` (optional): Timezone for the report (default: UTC)

### 4. `create_async_report`
Creates an asynchronous report for larger data sets.

**Parameters:**
- `from_date`: Start date in YYYY-MM-DD format
- `to_date`: End date in YYYY-MM-DD format
- `dimensions`: List of dimensions to include (e.g. ["campaignId", "campaign"])
- `metrics`: List of metrics to include (e.g. ["impressions", "clicks", "spend"])

### 5. `get_async_report_status`
Checks the status of an asynchronous report.

**Parameters:**
- `report_id`: ID of the async report to check

### 6. `get_async_report_results`
Gets the results of a completed asynchronous report.

**Parameters:**
- `report_id`: ID of the async report to retrieve

### 7. `get_available_metrics_and_dimensions`
Gets a list of all available metrics and dimensions for reporting.

## Example Queries for Claude

Here are some example queries you can ask Claude when using this MCP server:

1. "Show me the campaign spend for the last 30 days"
2. "What was the daily spend for campaign ID 12345 last week?"
3. "Get me the performance metrics for all campaigns in January 2023"
4. "Create an async report with campaign and country dimensions and impressions, clicks, and spend metrics for Q1"
5. "What metrics and dimensions are available for Jampp reporting?"

## License

MIT