Skip to main content
Glama
Bucketeer MCP Server

Bucketeer MCP Server

by nnnkkk7

Bucketeer MCP Server

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

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)

Related MCP server: hackle-mcp

Prerequisites

  • Node.js 18 or higher

  • A Bucketeer instance with API access

  • An API key with appropriate permissions (READ, WRITE, or ADMIN)

Installation

  1. Clone this repository:

git clone https://github.com/yourusername/bucketeer-mcp.git
cd bucketeer-mcp
  1. Install dependencies:

npm install
  1. Build the project:

npm run build
  1. Create a .env file based on .env.example:

cp .env.example .env
  1. Configure your environment variables in .env:

BUCKETEER_HOST=api.bucketeer.io
BUCKETEER_API_KEY=your-api-key-here
BUCKETEER_ENVIRONMENT_ID=your-environment-id
LOG_LEVEL=info

Usage

Running the Server

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:

{
  "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.

API Key Permissions

Different operations require different permission levels:

  • READ: Required for listFeatureFlags and getFeatureFlag

  • WRITE: Required for createFeatureFlag, updateFeatureFlag, and archiveFeatureFlag

Development

Project Structure

bucketeer-mcp/
├── src/
│   ├── api/
│   │   └── client.ts       # Bucketeer API client
│   ├── tools/
│   │   ├── list-flags.ts   # List feature flags tool
│   │   ├── create-flag.ts  # Create feature flag tool
│   │   ├── get-flag.ts     # Get feature flag tool
│   │   ├── update-flag.ts  # Update feature flag tool
│   │   ├── archive-flag.ts # Archive feature flag tool
│   │   └── index.ts        # Tool exports
│   ├── types/
│   │   └── bucketeer.ts    # TypeScript type definitions
│   ├── utils/
│   │   └── logger.ts       # Logging utility
│   ├── config.ts           # Configuration management
│   ├── server.ts           # MCP server implementation
│   └── index.ts            # Entry point
├── .env.example            # Environment variables template
├── .gitignore
├── package.json
├── tsconfig.json
└── README.md

Linting

Run the linter:

npm run lint

Building

Build the TypeScript code:

npm run build

Troubleshooting

Common Issues

  1. Authentication errors: Ensure your API key is valid and has the necessary permissions

  2. Environment ID not found: Verify the environment ID exists in your Bucketeer instance

  3. Connection errors: Check that the BUCKETEER_HOST is correct and accessible

Logging

The server logs to stderr in JSON format. Adjust the log level using the LOG_LEVEL environment variable:

  • error - Only errors

  • warn - Warnings and errors

  • info - General information (default)

  • debug - Detailed debug information

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Available Tools

5 tools
archiveFeatureFlagC

Archive a feature flag (make it inactive)

Inputs: id (required), comment (required), environmentId.

createFeatureFlagC

Create a new feature flag in the specified environment

Inputs: id (required), name (required), variations (required), defaultOnVariationIndex (required), +5 more.

getFeatureFlagC

Get a specific feature flag by ID

Inputs: id (required), environmentId, featureVersion.

listFeatureFlagsC

List all feature flags in the specified environment

Inputs: environmentId, pageSize, cursor, tags, +5 more.

updateFeatureFlagC

Update an existing feature flag

Inputs: id (required), comment (required), environmentId, name, +4 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose targeting specific CRUD operations on feature flags: list (retrieve all), get (retrieve one), create (add new), update (modify existing), and archive (deactivate). No ambiguity exists between these actions, making tool selection straightforward for an agent.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern (e.g., listFeatureFlags, createFeatureFlag) with perfect adherence to camelCase. The naming is predictable and readable across all five tools, with no deviations in style or convention.

    Tool Count5/5

    With 5 tools, this server is well-scoped for managing feature flags, covering essential CRUD operations plus archiving. Each tool earns its place without redundancy, and the count is appropriate for the domain, avoiding being too sparse or bloated.

    Completeness5/5

    The tool set provides complete lifecycle coverage for feature flags: create, read (list and get), update, and archive (as a soft delete). There are no obvious gaps, and agents can perform all core operations without dead ends in the domain of feature flag management.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers