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.