@drbarq/doppler-mcp

v1.0.7

Published

6 months ago

MCP server for Doppler API with auto-generated tools from OpenAPI specification

Downloads

0High
0Medium
0Low

drbarq

mcp doppler secrets api openapi model-context-protocol

Doppler MCP Server

A TypeScript MCP (Model Context Protocol) server that auto-generates tools from the Doppler API OpenAPI specification, providing seamless access to Doppler's secrets management capabilities.

Features

🚀 Auto-generated Tools: Automatically creates MCP tools from Doppler's OpenAPI specification
🔐 Full API Coverage: Supports all 105+ Doppler API endpoints
🛡️ Secure Authentication: Uses Bearer token authentication with proper error handling
📝 Type-Safe: Built with TypeScript and Zod schema validation
🔧 Easy Setup: Simple NPX installation and usage
🌐 Complete HTTP Support: Handles GET, POST, PUT, PATCH, and DELETE requests
⚡ Fast: Built on the FastMCP framework for optimal performance

Installation

NPX (Recommended)

# Run directly with NPX
DOPPLER_TOKEN=dp.your-token-here npx @drbarq/doppler-mcp

# Read-only mode
DOPPLER_TOKEN=dp.your-token-here npx @drbarq/doppler-mcp --read-only

# With project filter
DOPPLER_TOKEN=dp.your-token-here npx @drbarq/doppler-mcp --project my-app

Manual Installation

# Clone the repository
git clone https://github.com/drbarq/doppler-mcp.git
cd doppler-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Run the server
DOPPLER_TOKEN=dp.your-token-here npm start

Setup

1. Get Your Doppler API Token

Visit Doppler Dashboard
Click "Generate Token"
Choose appropriate permissions for your use case
Copy the generated token (starts with dp.)

2. Set Environment Variable

export DOPPLER_TOKEN=dp.your-actual-token-here

3. Run the Server

npx @drbarq/doppler-mcp

Command Line Options

The server supports several command-line options for customization. Each flag significantly impacts which tools are available and how they behave:

🔒 `--read-only`

Impact: Filters tools to only GET operations, removing all write capabilities.

Tools Before: 105 total endpoints
Tools After: ~35 read-only endpoints
Auto-removes: All POST, PUT, PATCH, DELETE operations
Perfect for: Monitoring dashboards, audit workflows, or when you only need to read secrets

npx @drbarq/doppler-mcp --read-only

📁 `--project <name>`

Impact: Filters tools to project-specific operations and auto-injects project parameter.

Tools Filtered: Keeps project-related endpoints and non-project-specific tools
Auto-injection: Automatically adds project: "my-app" to all tool calls that accept it
Perfect for: Working exclusively within one project context

npx @drbarq/doppler-mcp --project my-app

⚙️ `--config <name>`

Impact: Dramatically filters tools to config and secret management only.

Tools Before: 105 total endpoints
Tools After: 31 config/secret-related endpoints (70% reduction)
Keeps Only:
- All /configs/ endpoints (28 tools)
- All /secrets/ endpoints (2 tools)
- Tools with "config" in name (16 tools)
- Tools with "secret" in name (9 tools)
Auto-injection: Automatically adds config: "production" to all tool calls that accept it
Perfect for: Managing secrets in a specific config without clutter

npx @drbarq/doppler-mcp --config production

Config-Scoped Tools Include:

secrets_list, secrets_get, secrets_update, secrets_delete
configs_get, configs_update, configs_lock, configs_unlock
config_logs_list, config_logs_get, config_logs_rollback
dynamic_secrets_issue_lease, dynamic_secrets_revoke_lease

🌍 `--environment <name>`

Impact: Currently parsed but filtering not yet implemented.

Status: Planned for future release
Intended Use: Filter tools to environment-specific operations

npx @drbarq/doppler-mcp --environment prod

🔗 Flag Combinations

Flags can be combined for powerful scoping:

# Read-only access to a specific config (most restrictive)
npx @drbarq/doppler-mcp --read-only --config production

# Project-scoped with config filtering
npx @drbarq/doppler-mcp --project my-app --config production

# Read-only project management
npx @drbarq/doppler-mcp --read-only --project my-app

📊 Tool Count Impact by Flag Combination

| Flags | Tool Count | Use Case | |-------|------------|----------| | None | 105 | Full Doppler API access | | --read-only | ~35 | Read-only monitoring | | --config production | 31 | Config/secret management only | | --read-only --config production | ~15 | Read-only config inspection | | --project my-app | ~105 | Project-scoped (with auto-injection) | | --read-only --project my-app | ~35 | Read-only project monitoring |

🚀 Real-World Usage Examples

📋 Scenario 1: Production Secret Monitoring

Goal: Read-only access to production secrets for monitoring dashboard

Setup:

# Generate read-only service token in Doppler UI: Project → Environment → Config → Access
DOPPLER_TOKEN=dp.st.prod.readonly123 npx @drbarq/doppler-mcp --read-only

Available Tools: ~15 read-only tools Example Operations:

secrets_list - Monitor all production secrets
configs_get - Check production config status
config_logs_list - Audit recent changes
secrets_get - Retrieve specific secret values (if needed)

Auto-Injection: Config parameter automatically set to "prod"

🔧 Scenario 2: Staging Environment Management

Goal: Full secret management for staging environment

Setup:

# Using read/write service token
DOPPLER_TOKEN=dp.st.staging.readwrite456 npx @drbarq/doppler-mcp

Available Tools: ~31 config/secret management tools Example Operations:

secrets_update - Rotate staging API keys
secrets_create - Add new environment variables
configs_lock - Lock config during deployment
dynamic_secrets_issue_lease - Generate temporary database credentials

Auto-Injection: Config parameter automatically set to "staging"

🏢 Scenario 3: Multi-Project Development

Goal: Work across multiple projects with personal token

Setup:

# Using personal token for full workplace access
DOPPLER_TOKEN=dp.pt.personal789 npx @drbarq/doppler-mcp

Available Tools: All 105 tools Example Operations:

projects_list - See all available projects
environments_list → configs_list - Explore project structure
users_list - Manage team access
project_members_add - Add developers to projects

Auto-Injection: None (specify project/config manually for each operation)

🎯 Scenario 4: Focused Config Management

Goal: Manage only production config of specific project

Setup:

# Combine project and config filtering with personal token
DOPPLER_TOKEN=dp.pt.personal789 npx @drbarq/doppler-mcp --project my-app --config production

Available Tools: 31 config/secret tools (highly focused) Example Operations:

secrets_list - List production secrets
secrets_update - Update production values
config_logs_rollback - Rollback changes if needed
configs_add_trusted_ip - Manage IP restrictions

Auto-Injection: Both project: "my-app" and config: "production"

🔄 Scenario 5: CI/CD Integration

Goal: Automated secret retrieval in deployment pipeline

Setup:

# Read-only service token in CI environment
export DOPPLER_TOKEN=dp.st.prod.ci-readonly
npx @drbarq/doppler-mcp --read-only

Available Tools: ~15 read-only tools Typical CI Usage:

secrets_download - Export all secrets as environment file
secrets_list - Verify required secrets exist
configs_get - Check config status before deployment

Auto-Injection: Config automatically scoped to token's config

🛡️ Scenario 6: Security Audit Workflow

Goal: Comprehensive security review across workplace

Setup:

# Personal token with admin permissions
DOPPLER_TOKEN=dp.pt.admin123 npx @drbarq/doppler-mcp --read-only

Available Tools: ~35 read-only tools across all scopes Audit Operations:

activity_logs_list - Review recent workplace activity
users_list - Audit user access levels
project_members_list - Check project permissions
service_tokens_list - Review active service tokens
webhooks_list - Audit integrations

Auto-Injection: None (manual scoping for comprehensive audit)

Usage

Once the server is running, it will automatically generate MCP tools for all Doppler API endpoints. The available tools depend on your token type and CLI flags:

Secret Management

get_secrets - Retrieve secrets from a config
create_secret - Create a new secret
update_secret - Update an existing secret
delete_secret - Delete a secret

Project Management

list_projects - Get all projects
create_project - Create a new project
get_project - Retrieve project details
update_project - Update project settings

User Management

list_workplace_users - Get all workplace users
invite_user - Invite a new user
remove_user - Remove a user from workplace

And Many More!

The server automatically generates tools for all available Doppler API endpoints, including:

Environment management
Config management
Audit logs
Service tokens
Integrations
And 100+ other endpoints

Available Tools

The server generates tools based on the OpenAPI specification's operationId fields. Here's a sample of available tools:

| Tool Name | Description | HTTP Method | |-----------|-------------|-------------| | workplace_get | Retrieve workplace information | GET | | workplace_update | Update workplace settings | POST | | users_list | Get all users within a workplace | GET | | users_get | Get a specific user in a workplace | GET | | projects_list | List all projects | GET | | projects_create | Create a new project | POST | | configs_list | List all configs in a project | GET | | secrets_list | List all secrets in a config | GET | | secrets_create | Create a new secret | POST | | secrets_update | Update an existing secret | POST | | secrets_delete | Delete a secret | DELETE |

MCP Client Configuration

Configure the Doppler MCP server in your MCP client (like Claude Desktop). The configuration significantly impacts available tools and auto-injection behavior:

🏢 Production Configuration (Service Token)

Recommended for production environments

{
  "mcpServers": {
    "doppler-prod": {
      "command": "npx",
      "args": [
        "-y",
        "@drbarq/doppler-mcp@latest"
      ],
      "env": {
        "DOPPLER_TOKEN": "dp.st.prod.your-service-token"
      }
    }
  }
}

Token: Service token (read/write or read-only)
Tools: ~31 config/secret tools (auto-scoped to token's config)
Auto-injection: Config parameter automatically injected
Security: Highest - limited scope, no workplace access

🔒 Read-Only Monitoring Configuration

Perfect for dashboards and monitoring

{
  "mcpServers": {
    "doppler-monitor": {
      "command": "npx",
      "args": [
        "-y",
        "@drbarq/doppler-mcp@latest",
        "--read-only"
      ],
      "env": {
        "DOPPLER_TOKEN": "dp.st.prod.your-readonly-token"
      }
    }
  }
}

Token: Read-only service token
Tools: ~15 read-only config/secret tools
Operations: Only GET operations (secrets_list, configs_get, etc.)
Security: Maximum - read-only + config-scoped

⚙️ Config-Specific Management

For managing specific configs with personal token

{
  "mcpServers": {
    "doppler-staging": {
      "command": "npx",
      "args": [
        "-y",
        "@drbarq/doppler-mcp@latest",
        "--config",
        "staging"
      ],
      "env": {
        "DOPPLER_TOKEN": "dp.pt.your-personal-token"
      }
    }
  }
}

Token: Personal token
Tools: 31 config/secret tools (filtered to staging config)
Auto-injection: config: "staging" added to all tool calls
Perfect for: Focused config management without workplace clutter

📁 Project-Scoped Development

For working within a specific project

{
  "mcpServers": {
    "doppler-myapp": {
      "command": "npx",
      "args": [
        "-y",
        "@drbarq/doppler-mcp@latest",
        "--project",
        "my-app"
      ],
      "env": {
        "DOPPLER_TOKEN": "dp.pt.your-personal-token"
      }
    }
  }
}

Token: Personal token
Tools: All 105 tools
Auto-injection: project: "my-app" added to relevant tool calls
Perfect for: Project-focused development work

🔗 Combined Scoping (Most Focused)

Ultra-focused config management

{
  "mcpServers": {
    "doppler-app-prod": {
      "command": "npx",
      "args": [
        "-y",
        "@drbarq/doppler-mcp@latest",
        "--project",
        "my-app",
        "--config",
        "production"
      ],
      "env": {
        "DOPPLER_TOKEN": "dp.pt.your-personal-token"
      }
    }
  }
}

Token: Personal token
Tools: 31 config/secret tools
Auto-injection: Both project: "my-app" and config: "production"
Perfect for: Surgical config management within specific project

🛠️ Development Configuration (Full Access)

For development with full API access

{
  "mcpServers": {
    "doppler-dev": {
      "command": "npx",
      "args": [
        "-y",
        "@drbarq/doppler-mcp@latest"
      ],
      "env": {
        "DOPPLER_TOKEN": "dp.pt.your-personal-token"
      }
    }
  }
}

Token: Personal token
Tools: All 105 tools
Operations: Full workplace management capabilities
Auto-injection: None (manual parameter specification)
Perfect for: Development, testing, administrative tasks

🔄 Multiple Environments Setup

Run multiple scoped servers simultaneously

{
  "mcpServers": {
    "doppler-prod-readonly": {
      "command": "npx",
      "args": ["-y", "@drbarq/doppler-mcp@latest", "--read-only"],
      "env": { "DOPPLER_TOKEN": "dp.st.prod.readonly-token" }
    },
    "doppler-staging-rw": {
      "command": "npx",
      "args": ["-y", "@drbarq/doppler-mcp@latest"],
      "env": { "DOPPLER_TOKEN": "dp.st.staging.readwrite-token" }
    },
    "doppler-dev-full": {
      "command": "npx",
      "args": ["-y", "@drbarq/doppler-mcp@latest"],
      "env": { "DOPPLER_TOKEN": "dp.pt.your-personal-token" }
    }
  }
}

📊 Configuration Impact Matrix

| Configuration | Token Type | Tools Available | Auto-Injection | Use Case | |--------------|------------|-----------------|----------------|-----------| | Basic Service Token | dp.st.* | ~31 config/secret | Config name | Production | | Read-Only Service | dp.st.* + --read-only | ~15 read-only | Config name | Monitoring | | Config-Scoped Personal | dp.pt.* + --config | 31 config/secret | Config name | Focused management | | Project-Scoped Personal | dp.pt.* + --project | 105 all tools | Project name | Project development | | Combined Scoping | dp.pt.* + --project + --config | 31 config/secret | Both project & config | Surgical precision | | Full Access Personal | dp.pt.* | 105 all tools | None | Development/admin |

Configuration

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | DOPPLER_TOKEN | Yes | - | Your Doppler API token (starts with dp.) | | DOPPLER_BASE_URL | No | https://api.doppler.com | Base URL for Doppler API |

🔑 Doppler Token Types & Permissions

The type of Doppler token you use determines which tools are available and their behavior. Understanding token types is crucial for proper MCP server operation:

📋 Personal Tokens (`dp.pt.*`)

Scope: Full workplace access with user's permissions

Generated: User Settings → API → Personal Tokens
Permissions: Inherits all user workplace and project permissions
Best For: Development, testing, full administrative access
Available Tools: All 105 tools (based on user's role permissions)
Limitations: Tied to individual user account

Example Use Cases:

# Full administrative access
DOPPLER_TOKEN=dp.pt.xxxx npx @drbarq/doppler-mcp

# Personal token with read-only safety
DOPPLER_TOKEN=dp.pt.xxxx npx @drbarq/doppler-mcp --read-only

🔧 Service Tokens (`dp.st.*`)

Scope: Limited to specific config with read or read/write access

Generated: Project → Environment → Config → Access → Service Tokens
Permissions: Config-scoped only (cannot access other configs/projects)
Best For: Production deployments, CI/CD, scoped automation
Available Tools: Automatically filtered to config-relevant tools
Auto-Scoping: Behaves like --config <config-name> is always applied

Service Token Access Levels:

🔒 Read-Only Service Token

Tools Available: ~15 read-only config/secret tools
Operations: secrets_list, secrets_get, configs_get, config_logs_list
Cannot: Create, update, or delete secrets
Perfect For: Monitoring, auditing, secret retrieval

✏️ Read/Write Service Token

Tools Available: ~31 config/secret management tools
Operations: All secret and config operations within the token's config
Can: Create, update, delete secrets; manage config settings
Perfect For: Application deployment, secret rotation

Service Token Behavior:

# Service token automatically scopes to its config
DOPPLER_TOKEN=dp.st.dev.xxxx npx @drbarq/doppler-mcp
# Equivalent to: --config dev (automatically applied)

# Adding --read-only further restricts a read/write service token
DOPPLER_TOKEN=dp.st.prod.xxxx npx @drbarq/doppler-mcp --read-only

🏢 CLI Tokens (`dp.ct.*`)

Scope: User authentication for CLI operations

Generated: doppler login command
Permissions: Same as personal tokens but for CLI use
Best For: Interactive CLI sessions
Available Tools: All 105 tools (based on user's permissions)
Note: Primarily for Doppler CLI, but works with MCP server

📊 Token Type Tool Matrix

| Token Type | All Tools | Config Tools Only | Auto-Config-Scope | User Permissions | |------------|-----------|-------------------|-------------------|------------------| | Personal (dp.pt.*) | ✅ | With --config | ❌ | ✅ User's roles | | Service Read-Only (dp.st.*) | ❌ | ✅ | ✅ | ❌ Config read only | | Service Read/Write (dp.st.*) | ❌ | ✅ | ✅ | ❌ Config read/write | | CLI (dp.ct.*) | ✅ | With --config | ❌ | ✅ User's roles |

🚨 Token Security Best Practices

Production: Always use service tokens, never personal tokens
Development: Personal tokens for full access, service tokens for testing specific configs
CI/CD: Read-only service tokens for deployments that only need secret retrieval
Monitoring: Read-only service tokens with --read-only flag for extra safety
Principle of Least Privilege: Use most restrictive token type that meets your needs

🔍 Token Permission Validation

The MCP server automatically validates token permissions on startup:

# ✅ Valid service token
DOPPLER_TOKEN=dp.st.prod.xxxx npx @drbarq/doppler-mcp
# Console: "✓ Successfully connected to Doppler API (Service Token: read/write access to 'prod' config)"

# ❌ Invalid/expired token  
DOPPLER_TOKEN=dp.st.invalid.xxxx npx @drbarq/doppler-mcp
# Console: "Failed to connect to Doppler API: 401 Unauthorized"

💡 Token Type Detection & Auto-Configuration

The server automatically detects token type and optimizes behavior:

Service Tokens: Auto-applies config filtering (like --config flag)
Personal/CLI Tokens: Provides full tool access unless flags specified
Read-Only Service Tokens: Automatically behaves like --read-only flag

Development

Prerequisites

Node.js 18+
TypeScript 5+
A valid Doppler API token

Setup

# Clone the repository
git clone https://github.com/drbarq/doppler-mcp.git
cd doppler-mcp

# Install dependencies
npm install

# Set your token
export DOPPLER_TOKEN=dp.your-token-here

# Run in development mode
npm run dev

Project Structure

doppler-mcp/
├── src/
│   ├── index.ts          # Main server entry point
│   ├── parser.ts         # OpenAPI specification parser
│   ├── generator.ts      # MCP tool generator
│   ├── client.ts         # HTTP client with error handling
│   ├── auth.ts           # Authentication management
│   └── types.ts          # TypeScript type definitions
├── bin/
│   └── doppler-mcp       # NPX executable
├── doppler-openapi.json  # Doppler API OpenAPI specification
├── package.json
├── tsconfig.json
└── README.md

Building

npm run build

This will:

Compile TypeScript to JavaScript in the dist/ directory
Copy the OpenAPI specification to the dist/ directory

Publishing to NPM

The package is published to the public NPM registry as @drbarq/doppler-mcp:

Build and publish:
```
npm run build
npm publish
```
The package is configured with "publishConfig": { "access": "public" } for public access on NPM.

Error Handling

The server includes comprehensive error handling:

Authentication Errors: Clear messages for invalid or missing tokens
API Errors: Detailed error responses from the Doppler API
Validation Errors: Schema validation for tool inputs using Zod
Network Errors: Proper handling of connection issues

API Reference

The server exposes tools based on Doppler's REST API. For detailed API documentation, visit:

Contributing

Fork the repository
Create a feature branch: git checkout -b feature-name
Make your changes
Add tests if applicable
Commit your changes: git commit -am 'Add feature'
Push to the branch: git push origin feature-name
Submit a pull request

License

MIT License - see LICENSE file for details.

Support

Changelog

1.0.0

Initial release
Auto-generation of MCP tools from OpenAPI specification
Full Doppler API coverage (105+ endpoints)
TypeScript support with Zod validation
NPX installation support
Comprehensive error handling

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Doppler MCP Server

Features

Installation

NPX (Recommended)

Manual Installation

Setup

1. Get Your Doppler API Token

2. Set Environment Variable

3. Run the Server

Command Line Options

🔒 --read-only

📁 --project <name>

⚙️ --config <name>

🌍 --environment <name>

🔗 Flag Combinations

📊 Tool Count Impact by Flag Combination

🚀 Real-World Usage Examples

📋 Scenario 1: Production Secret Monitoring

🔧 Scenario 2: Staging Environment Management

🏢 Scenario 3: Multi-Project Development

🎯 Scenario 4: Focused Config Management

🔄 Scenario 5: CI/CD Integration

🛡️ Scenario 6: Security Audit Workflow

Usage

Secret Management

Project Management

User Management

And Many More!

Available Tools

MCP Client Configuration

🏢 Production Configuration (Service Token)

🔒 Read-Only Monitoring Configuration

⚙️ Config-Specific Management

📁 Project-Scoped Development

🔗 Combined Scoping (Most Focused)

🛠️ Development Configuration (Full Access)

🔄 Multiple Environments Setup

📊 Configuration Impact Matrix

Configuration

Environment Variables

🔑 Doppler Token Types & Permissions

📋 Personal Tokens (dp.pt.*)

🔧 Service Tokens (dp.st.*)

🔒 Read-Only Service Token

✏️ Read/Write Service Token

🏢 CLI Tokens (dp.ct.*)

📊 Token Type Tool Matrix

🚨 Token Security Best Practices

🔍 Token Permission Validation

💡 Token Type Detection & Auto-Configuration

Development

Prerequisites

Setup

Project Structure

Building

Publishing to NPM

Error Handling

API Reference

Contributing

License

Support

Changelog

1.0.0

🔒 `--read-only`

📁 `--project <name>`

⚙️ `--config <name>`

🌍 `--environment <name>`

📋 Personal Tokens (`dp.pt.*`)

🔧 Service Tokens (`dp.st.*`)

🏢 CLI Tokens (`dp.ct.*`)