Statsig MCP Server

Model Context Protocol server for Statsig feature flags and experimentation platform.

This MCP server enables AI assistants to interact with Statsig's Console API for comprehensive feature management and experimentation platform administration.

Features

🚩 Feature Gate Management: Create, read, update, and delete feature gates
⚙️ Dynamic Configuration Management: Full CRUD operations for dynamic configs
🧪 Experiment Management: Create, read, update, and delete experiments
👥 Segment Management: Create and manage user segments
📊 Metrics Access: View and analyze platform metrics
📈 Audit Logs: Track changes and access audit trail
🎯 Target Apps: Manage target applications
🔑 API Key Management: List and manage API keys
👤 Team Management: List team users and get user details by email
📋 Event Querying: List available event types in your project

Installation

Using uv (Recommended)

# Clone the repository
git clone https://github.com/GeLi2001/statsig-mcp.git
cd statsig-mcp

# Install dependencies with uv
uv sync

# Install with dev dependencies
uv sync --extra dev

Using pip

# Install from source
pip install -e .

# Or install with dev dependencies
pip install -e ".[dev]"

Quick Start

1. Get Your Console API Key

Go to Statsig Console
Navigate to Project Settings → Keys & Environments
Copy your Console API Key (not the client or server key)

2. Run the Server

With uv (Recommended):

# Using command-line arguments (MCP best practice)
uv run -m statsig_mcp --api-key "console-xxx"

# With additional options
uv run -m statsig_mcp \
  --api-key "console-xxx" \
  --environment "production" \
  --api-timeout 5000 \
  --debug

# Or with environment variables
STATSIG_CONSOLE_API_KEY="console-xxx" uv run -m statsig_mcp

With Python:

# Using flags (recommended)
python -m statsig_mcp --api-key "console-xxx"

# Or environment variables
export STATSIG_CONSOLE_API_KEY="console-xxx"
python -m statsig_mcp

3. Configuration Options

The server supports both command-line arguments (recommended for MCP) and environment variables:

Command-Line Arguments (MCP Best Practice)

uv run -m statsig_mcp --help

Argument	Type	Default	Description
`--api-key`	string	None	Statsig Console API key (required)
`--environment`	string	development	Environment tier
`--api-timeout`	int	3000	API timeout in milliseconds
`--disable-logging`	flag	false	Disable event logging to Statsig
`--debug`	flag	false	Enable debug logging

Environment Variables (Fallback)

Variable	Description
`STATSIG_CONSOLE_API_KEY`	Statsig Console API key
`STATSIG_ENVIRONMENT`	Environment tier
`STATSIG_API_TIMEOUT`	API timeout in milliseconds
`STATSIG_DISABLE_LOGGING`	Disable logging (true/false)
`STATSIG_DEBUG`	Enable debug mode (true/false)

4. MCP Client Configuration

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "statsig": {
      "command": "uv",
      "args": [
        "run",
        "-m",
        "statsig_mcp",
        "--api-key",
        "console-xxx",
        "--environment",
        "production"
      ]
    }
  }
}

Alternative with Environment Variables

{
  "mcpServers": {
    "statsig": {
      "command": "uv",
      "args": ["run", "-m", "statsig_mcp"],
      "env": {
        "STATSIG_CONSOLE_API_KEY": "console-xxx",
        "STATSIG_ENVIRONMENT": "production"
      }
    }
  }
}

5. Test with MCP Inspector

# Test your server with the MCP Inspector
npx @modelcontextprotocol/inspector uv --directory . run statsig-mcp --api-key console-xxx

Available Tools

The server provides 27 Console API tools organized by resource type:

Feature Gates Management

list_gates: List all feature gates
get_gate: Get details of a specific feature gate
create_gate: Create a new feature gate
update_gate: Update an existing feature gate
delete_gate: Delete a feature gate

Experiments Management

list_experiments: List all experiments
get_experiment: Get details of a specific experiment
create_experiment: Create a new experiment
update_experiment: Update an existing experiment
delete_experiment: Delete an experiment

Dynamic Configs Management

list_dynamic_configs: List all dynamic configs
get_dynamic_config: Get details of a specific dynamic config
create_dynamic_config: Create a new dynamic config
update_dynamic_config: Update an existing dynamic config
delete_dynamic_config: Delete a dynamic config

Segments Management

list_segments: List all segments
get_segment: Get details of a specific segment
create_segment: Create a new segment

Analytics & Monitoring

list_metrics: List all metrics
get_metric: Get details of a specific metric
list_audit_logs: List audit logs with optional date filtering

Platform Management

list_target_apps: List all target apps
get_target_app: Get details of a specific target app
list_api_keys: List all API keys

Team & Events

list_team_users: List all team members
get_user_by_email: Get team member info by email
query_events: Query event types and details

Example Usage

Create a Feature Gate

{
  "name": "new_checkout_flow",
  "description": "Enable new checkout flow for users",
  "is_enabled": true
}

**Parameters:**

- `user_id` (string): User identifier
- `experiment_name` (string): Name of the experiment
- `user_email` (string, optional): User email
- `user_country` (string, optional): User country code
- `custom_attributes` (object, optional): Custom user attributes

#### 4. `get_layer`

Get layer parameter values for a user.

**Parameters:**

- `user_id` (string): User identifier
- `layer_name` (string): Name of the layer
- `user_email` (string, optional): User email
- `user_country` (string, optional): User country code
- `custom_attributes` (object, optional): Custom user attributes

#### 5. `log_event`

Log a custom event directly to Statsig.

**Parameters:**

- `user_id` (string): User identifier
- `event_name` (string): Name of the event
- `value` (string|number, optional): Event value
- `metadata` (object, optional): Event metadata
- `user_email` (string, optional): User email
- `user_country` (string, optional): User country code
- `custom_attributes` (object, optional): Custom user attributes

### Project Management

#### 6. `query_events`

List all event types configured in your Statsig project.

**Parameters:** None

**Returns:** List of event names and their configurations.

#### 7. `get_user_by_email`

Get team member information by email address.

**Parameters:**

- `email` (string): Email address of the team member

#### 8. `list_team_users`

List all team members in your Statsig project.

**Parameters:** None

**Returns:** List of team members with their roles and permissions.

## Example MCP Client Usage

```python
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

# Create server parameters with flags (recommended)
server_params = StdioServerParameters(
    command="uv",
    args=[
        "run", "-m", "statsig_mcp",
        "--api-key", "console-xxx",
        "--environment", "production",
        "--debug"
    ]
)

async def main():
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()

            # Check a feature gate
            result = await session.call_tool(
                "check_feature_gate",
                arguments={
                    "user_id": "user123",
                    "gate_name": "new_feature",
                    "custom_attributes": {"plan": "premium"}
                }
            )
            print(f"Feature gate result: {result}")

            # Get dynamic config
            config = await session.call_tool(
                "get_dynamic_config",
                arguments={
                    "user_id": "user123",
                    "config_name": "ui_config"
                }
            )
            print(f"Config: {config}")

            # Log an event
            await session.call_tool(
                "log_event",
                arguments={
                    "user_id": "user123",
                    "event_name": "button_click",
                    "metadata": {"button": "checkout"}
                }
            )

            # List available events
            events = await session.call_tool("query_events")
            print(f"Available events: {events}")

            # Get team member info
            user_info = await session.call_tool(
                "get_user_by_email",
                arguments={"email": "teammate@company.com"}
            )
            print(f"Team member: {user_info}")

Development

Setup Development Environment

Using uv (Recommended):

# Clone and setup
git clone https://github.com/GeLi2001/statsig-mcp.git
cd statsig-mcp

# Install all dependencies including dev tools
uv sync --extra dev

# Run tests
uv run pytest

# Format code
uv run black .

# Type checking
uv run mypy .

# Linting
uv run ruff check .

Using pip:

# Install in development mode with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Format code
black .

# Type checking
mypy .

Running Commands

With uv, you can run any command in the virtual environment:

# Run the server with flags
uv run -m statsig_mcp --api-key "console-xxx" --debug

# Run tests with verbose output
uv run pytest -v

# Run validation script
uv run python validate.py

# Format and lint
uv run black .
uv run ruff check --fix .

Project Structure

statsig_mcp/
├── __init__.py
├── __main__.py           # Module entry point
├── server.py             # Main MCP server implementation
├── console_client.py     # Statsig Console API client
└── types.py              # Type definitions

tests/                    # Test suite
├── test_server.py

examples/                 # Usage examples
├── client_example.py

pyproject.toml            # Project configuration
uv.lock                   # Locked dependencies (uv)
.venv/                    # Virtual environment (uv managed)

Architecture

This MCP server uses a hybrid approach with three Statsig APIs:

Console API (https://statsigapi.net/console/v1/*) - For project management (team users, event types)
HTTP API (https://api.statsig.com/v1/*) - For real-time feature checks (gates, configs, experiments, layers)
Events API (https://events.statsigapi.net/v1/*) - For direct event logging

This approach provides the best balance of functionality and performance, allowing both management operations and real-time feature evaluation.

Security Notes

Never expose your Statsig Console API key in client-side code
Use command-line arguments or environment variables for API keys
The Console API key provides full access to your Statsig project
Consider using separate API keys for different environments
Console API keys are different from client keys and server secret keys

Requirements

Python 3.10+
uv (recommended) or pip for package management

Troubleshooting

Common Issues

"API key not found" error: Ensure --api-key is provided or STATSIG_CONSOLE_API_KEY is set
Network timeouts: Increase timeout with --api-timeout 5000
Feature gate not found: Verify the gate name exists in your Statsig console
Python version error: This package requires Python 3.10+ (MCP requirement)
Wrong API key type: Make sure you're using a Console API key, not a client or server key

Debug Mode

Enable debug logging for troubleshooting:

# With command-line flag (recommended)
uv run -m statsig_mcp --api-key "console-xxx" --debug

# With environment variable
STATSIG_DEBUG=true uv run -m statsig_mcp --api-key "console-xxx"

Help

Get help with command-line options:

uv run -m statsig_mcp --help

License

MIT License - see LICENSE file for details.

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Run tests and linting: uv run pytest && uv run ruff check
Submit a pull request

Resources