Doppler MCP Server

MCP (Model Context Protocol) server that provides AI assistants with access to the Doppler API for secrets management.

Important

The Doppler MCP Server is experimental and intended for development, testing, and evaluation purposes. Because outputs are non-deterministic and vary with the connected model, query, and server configuration, always use a token scoped only to the actions, projects, and environments you intend to allow, and review agentic output for alignment with your security and compliance requirements.

Quick Start

1. Authenticate:

npx @dopplerhq/mcp-server login

2. Add to your MCP client configuration (e.g., Claude Desktop):

{
  "mcpServers": {
    "doppler": {
      "command": "npx",
      "args": ["-y", "@dopplerhq/mcp-server"]
    }
  }
}

With Service Token

Alternatively, use a service token instead of logging in:

{
  "mcpServers": {
    "doppler": {
      "command": "npx",
      "args": ["-y", "@dopplerhq/mcp-server"],
      "env": {
        "DOPPLER_TOKEN": "<your-doppler-token>"
      }
    }
  }
}

See Service Tokens to create a config-scoped token.

Commands

login              Authenticate with Doppler (interactive)
logout             Clear cached auth credentials

Options

--read-only        Only expose read operations (GET endpoints)
--project <name>   Override auto-detected project
--config <name>    Override auto-detected config
--verbose, -v      Enable verbose logging to stderr
-h, --help         Show help message

Examples

Read-only mode

{
  "mcpServers": {
    "doppler": {
      "command": "npx",
      "args": ["-y", "@dopplerhq/mcp-server", "--read-only"]
    }
  }
}

Restrict to a specific project:

{
  "mcpServers": {
    "doppler": {
      "command": "npx",
      "args": ["-y", "@dopplerhq/mcp-server", "--project", "my-app"]
    }
  }
}

Restrict to a specific config:

{
  "mcpServers": {
    "doppler": {
      "command": "npx",
      "args": [
        "-y",
        "@dopplerhq/mcp-server",
        "--project",
        "my-app",
        "--config",
        "production"
      ]
    }
  }
}

Implicit Scope Detection

The server automatically detects scope based on your token's access:

Token Access	Auto-Detected Scope
Single project	--project set automatically
Single project + single config	--project and --config set automatically
Multiple projects	No auto-detection (use CLI flags)

This means scoped service tokens work out of the box without any CLI flags:

{
  "mcpServers": {
    "doppler": {
      "command": "npx",
      "args": ["-y", "@dopplerhq/mcp-server", "--read-only"],
      "env": {
        "DOPPLER_TOKEN": "dp.st.xxx"
      }
    }
  }
}

CLI flags always take precedence over auto-detected values.

Security Best Practices

Use scoped service tokens, not CLI flags, for access control. The --project and --config flags provide a convenient UX layer but are not a substitute for proper token scoping. Always create service tokens with the minimum required permissions:

1. Scope tokens to specific projects in the Doppler dashboard
2. Use read-only tokens when write access isn't needed
3. Combine read-only tokens with --read-only for defense in depth:

{
  "mcpServers": {
    "doppler": {
      "command": "npx",
      "args": ["-y", "@dopplerhq/mcp-server", "--read-only"],
      "env": {
        "DOPPLER_TOKEN": "dp.st.readonly_token"
      }
    }
  }
}

Note: The server cannot determine read/write permissions from the token, so if you're using a read-only token, add --read-only to only expose read tools. This prevents write tools from appearing in Claude's tool list and avoids failed API calls.

Available Tools

The server auto-generates tools from the Doppler OpenAPI spec. The tools available depend on your flags:

No flags (full access)

All Doppler API tools including:

• Workplace: workplace_get, workplace_update
• Users & Groups: users_list, groups_list, service_accounts_list
• Projects: projects_list, projects_create, projects_get, projects_delete
• Environments: environments_list, environments_create, environments_get
• Configs: configs_list, configs_create, configs_get, configs_update, configs_lock
• Secrets: secrets_list, secrets_get, secrets_update, secrets_download
• Integrations: integrations_list, syncs_list, webhooks_list

With --read-only

Read-only tools only (GET operations). Write operations like _create, _update, _delete are not exposed.

With --project

Org-level tools are filtered out (workplace_*, activity_logs_*). The project parameter is auto-injected into tool calls that accept it.

With --config

Only config and secret management tools:

• configs_get, configs_update, configs_lock, configs_unlock
• secrets_list, secrets_get, secrets_update, secrets_download
• config_logs_list, config_logs_rollback

Both project and config parameters are auto-injected.

Development

# Install dependencies
pnpm install

# Run tests
pnpm test

# Build
pnpm run build

# Run locally
DOPPLER_TOKEN=dp.xxx pnpm start

Branch and Release Flow

New work should branch from main and target main in PRs.

To release, push a tag in the format vX.X.X following semantic versioning. This triggers the publish workflow which builds and publishes to NPM.