Bucketeer MCP Server

A Model Context Protocol (MCP) server for managing feature flags in Bucketeer, an open-source feature flag management platform.

[!WARNING]

This is a beta version. Breaking changes may be introduced before general release.

Features

This MCP server provides tools for basic CRUD operations on Bucketeer feature flags:

• listFeatureFlags - List all feature flags with filtering and pagination
• createFeatureFlag - Create a new feature flag
• getFeatureFlag - Get a specific feature flag by ID
• updateFeatureFlag - Update an existing feature flag
• archiveFeatureFlag - Archive a feature flag (make it inactive)

Prerequisites

• Node.js 18 or higher
• A Bucketeer instance with API access
• An API key with appropriate permissions (READ, WRITE, or ADMIN)

Installation

Using npx (Recommended)

The easiest way to use Bucketeer MCP Server is directly with npx - no installation required:

npx @bucketeer/mcp

Local Installation

1. Clone this repository

git clone https://github.com/bucketeer-io/bucketeer-mcp.git
cd bucketeer-mcp

2. Install dependencies

npm install

3. Build the project

npm run build

Usage

Running the Server

Using npx (No Installation Required)

npx @bucketeer/mcp

Using Local Installation

Start the MCP server

npm start

For development with auto-reload

npm run dev

MCP Client Configuration

To use this server with an MCP client, add it to your MCP client configuration.

Using npx (Recommended)

{
  "mcpServers": {
    "bucketeer": {
      "command": "npx",
      "args": ["@bucketeer/mcp"],
      "env": {
        "BUCKETEER_HOST": "api.bucketeer.io",
        "BUCKETEER_API_KEY": "your-api-key",
        "BUCKETEER_ENVIRONMENT_ID": "your-environment-id"
      }
    }
  }
}

Using Local Installation

{
  "mcpServers": {
    "bucketeer": {
      "command": "node",
      "args": ["/path/to/bucketeer-mcp/dist/index.js"],
      "env": {
        "BUCKETEER_HOST": "api.bucketeer.io",
        "BUCKETEER_API_KEY": "your-api-key",
        "BUCKETEER_ENVIRONMENT_ID": "your-environment-id"
      }
    }
  }
}

Available Tools

listFeatureFlags

List all feature flags in the specified environment.

Parameters:

• environmentId (optional) - Environment ID (uses default if not provided)
• pageSize (optional) - Number of items per page (1-100, default: 20)
• cursor (optional) - Pagination cursor for next page
• tags (optional) - Filter by tags
• orderBy (optional) - Field to order by (CREATED_AT, UPDATED_AT, NAME)
• orderDirection (optional) - Order direction (ASC, DESC)
• searchKeyword (optional) - Search keyword for feature name or ID
• maintainer (optional) - Filter by maintainer email
• archived (optional) - Filter by archived status

createFeatureFlag

Create a new feature flag.

Parameters:

• id (required) - Unique identifier (alphanumeric, hyphens, underscores)
• name (required) - Human-readable name
• description (optional) - Description of the feature flag
• environmentId (optional) - Environment ID (uses default if not provided)
• variations (required) - Array of variations (at least 2)
• value (required) - The value returned when this variation is served
• name (required) - Name of the variation
• description (optional) - Description of the variation
• tags (optional) - Tags for the feature flag
• defaultOnVariationIndex (required) - Index of variation when flag is on (0-based)
• defaultOffVariationIndex (required) - Index of variation when flag is off (0-based)
• variationType (optional) - Type of the variation values: STRING (default), BOOLEAN, NUMBER, or JSON

getFeatureFlag

Get a specific feature flag by ID.

Parameters:

• id (required) - The ID of the feature flag to retrieve
• environmentId (optional) - Environment ID (uses default if not provided)
• featureVersion (optional) - Specific version of the feature to retrieve

updateFeatureFlag

Update an existing feature flag.

Parameters:

• id (required) - The ID of the feature flag to update
• comment (required) - Comment for the update (required for audit trail)
• environmentId (optional) - Environment ID (uses default if not provided)
• name (optional) - New name for the feature flag
• description (optional) - New description
• tags (optional) - New tags
• enabled (optional) - Enable or disable the feature flag
• archived (optional) - Archive or unarchive the feature flag

Note:

• This tool requires a comment for audit trail purposes
• It does not support updating variations. To modify variations, you would need to archive the current flag and create a new one.

archiveFeatureFlag

Archive a feature flag (make it inactive). Archived flags will return the default value defined in your code for all users.

Parameters:

• id (required) - The ID of the feature flag to archive
• environmentId (optional) - Environment ID (uses default if not provided)
• comment (required) - Comment for the archive action (required for audit trail)

Note: This operation archives the flag rather than permanently deleting it. The flag can be unarchived later if needed.

Development

Linting

Run the linter

npm run lint

Building

Build the TypeScript code

npm run build

Contributing

We would ❤️ for you to contribute to Bucketeer and help improve it! Anyone can use and enjoy it!

Please follow our contribution guide here.

License

Apache License 2.0, see LICENSE.