Doppler MCP Server Cursor IDE Setup 2026: npx, Login Flow & DOPPLER_TOKEN
Doppler MCP server Cursor IDE setup 2026: the official @dopplerhq/mcp-server npm package, the login-vs-DOPPLER_TOKEN auth split, --read-only and --project scoping flags, and why Doppler still calls this server experimental.
How do you set up the Doppler MCP server in Cursor? Add a doppler entry to ~/.cursor/mcp.json that runs npx -y @dopplerhq/mcp-server, then authenticate one of two ways: run npx @dopplerhq/mcp-server login once to store credentials in your system keyring for interactive local use, or set a DOPPLER_TOKEN environment variable for CI and shared machines. Restart Cursor, and the agent can query Doppler projects, configs, and secrets from chat.
Doppler — the secrets-management platform, not to be confused with a same-named unrelated tool — publishes this server itself under DopplerHQ/mcp-server on GitHub. It's a thin bridge to the Doppler API, not a replacement for the Doppler CLI or dashboard, and Doppler's own docs still label it experimental, meaning the tool set and defaults may shift faster than a GA integration.
What the Doppler MCP Server Actually Does
Once connected, Cursor's agent can:
That write capability is exactly why the login flow matters more here than on a read-only MCP server: an agent that can call write_secret-equivalent operations is an agent that can overwrite a production value if a prompt goes wrong. Doppler's own guidance is to treat this as evaluation-grade tooling, not something to wire into a fully unattended pipeline yet.
Prerequisites
npx @dopplerhq/mcp-server correctly)Step 1: Choose Your Auth Path
Doppler's server supports two distinct authentication models, and picking the wrong one for your situation is the most common setup mistake:
Interactive login (recommended for a personal dev machine):
npx @dopplerhq/mcp-server login
This opens a browser-based login flow and stores the resulting credentials in your system's keyring (Keychain on macOS, equivalent on Windows/Linux). Once logged in, you don't need to pass a token in mcp.json at all — the server reads from the keyring automatically.
DOPPLER_TOKEN environment variable (for CI/CD or shared machines):
Skip the login step and instead generate a Service Token or Service Account Token from the Doppler dashboard, scoped to a specific project and config (environment). This is the right choice whenever a human isn't sitting at the keyboard to complete a browser login — a CI runner, a shared build box, or a remote dev container.
Step 2: Add the Server to Cursor's mcp.json
If you've already run the login flow, the config is just the command — no token needed in the file:
{
"mcpServers": {
"doppler": {
"command": "npx",
"args": ["-y", "@dopplerhq/mcp-server"]
}
}
}
If you're using a DOPPLER_TOKEN instead (CI, shared machine, or you'd rather not rely on keyring storage), pass it as an environment variable in the config:
{
"mcpServers": {
"doppler": {
"command": "npx",
"args": ["-y", "@dopplerhq/mcp-server"],
"env": {
"DOPPLER_TOKEN": "dp.st.your-service-token-here"
}
}
}
}
Restart Cursor after saving either version. A green status under Settings → MCP confirms the process started; it doesn't yet confirm the token actually authenticates — that's Step 3.
Step 3: Scope Down with Read-Only and Project Flags
Because this server can write secrets, two flags matter more here than on most MCP servers you'd wire into Cursor:
{
"mcpServers": {
"doppler": {
"command": "npx",
"args": [
"-y", "@dopplerhq/mcp-server",
"--read-only",
"--project", "my-app",
"--config", "dev"
]
}
}
}
--read-only disables every write operation at the server level, regardless of what the underlying token permits — a hard stop before a mistaken "clean up unused secrets" prompt does something destructive. --project and --config narrow which Doppler project and environment the server will touch. Doppler's own documentation is explicit that these flags are a convenience, not a guaranteed security boundary — the token's actual scope is still the real enforcement point, so don't rely on --project alone to keep an agent out of production secrets if the underlying token can already reach them.
Step 4: Verify the Connection
In Cursor chat:
List the configs in my Doppler project and tell me which environments exist.
A response naming real project and config names confirms the connection and auth are both working. If Cursor reports an auth error, re-run the login flow or double-check the token value — a token pasted with a trailing newline or missing the dp.st. prefix is a common copy-paste failure mode.
Practical Workflows
Checking what a service expects before deploying
Show me every secret key defined in the "payments-api" config for the "prod" environment — just the keys, not the values.
Comparing dev and prod configs for drift
Compare the secret keys present in my "dev" config versus "prod" for the same project, and tell me if anything is missing from prod.
Auditing recent changes
Show me the last 10 activity log entries for this Doppler project — what changed and who changed it?
Downloading a config for local testing
Download the "staging" config as an env file so I can run this service locally against staging secrets.
When Not to Use This
Don't point a write-capable Doppler MCP connection at a production project inside a Cursor session that also has other, less-trusted MCP servers active — a prompt-injection chain that routes unrelated tool output into a write call is a realistic failure mode for any MCP server that can mutate state, and Doppler itself flags this integration as experimental and evaluation-grade rather than production-hardened. Use --read-only for anything beyond your own local development, and reserve write access for a dedicated, carefully scoped token.
Troubleshooting
Server starts but every call fails with an auth error
Confirm you actually completed the login flow (npx @dopplerhq/mcp-server login) if you're relying on keyring storage, or that DOPPLER_TOKEN is set correctly in the env block if you're using a token. Mixing the two — assuming login covers you when you're actually on a machine where the keyring entry never got created — is the most common cause.
"command not found" or npx fails to resolve the package
Confirm Node.js is version 20 or later with node --version. Older Node installations, common on machines that haven't been updated in a while, will fail to run the package correctly even if npx itself resolves.
Read operations work but writes silently do nothing
Check whether --read-only is set in your mcp.json args — if it is, that's working as intended, not a bug. Remove it deliberately, not accidentally, if you actually need write access.
Token works in the Doppler CLI but not in Cursor
Confirm you generated a Service Token or Service Account Token specifically, not a personal login session — the DOPPLER_TOKEN environment variable expects one of those two token types, and copying a different credential type produces an authentication failure that looks like a config problem.
Logging out or rotating credentials
npx @dopplerhq/mcp-server logout
Run this before re-authenticating with a different account or token, so stale keyring credentials don't silently keep working underneath a new login attempt.
Frequently Asked Questions
Q: Is the Doppler MCP server official, or a community wrapper?
A: Official — it's published and maintained by Doppler under DopplerHQ/mcp-server on GitHub as the @dopplerhq/mcp-server npm package, not a third-party integration.
Q: What does "experimental" mean here in practice?
A: Doppler's own docs describe the server as intended for development, testing, and evaluation — not yet positioned as a hardened production integration. Tool behavior and defaults may still change between releases faster than a GA product would.
Q: Do I need the Doppler CLI installed to use the MCP server?
A: No, it's optional. Doppler recommends having it available for automated environments, but the MCP server itself runs standalone via npx without requiring a separate CLI installation.
Q: What's the difference between the login flow and DOPPLER_TOKEN?
A: Login stores credentials in your system's keyring for interactive use on a personal machine — no token in mcp.json. DOPPLER_TOKEN is an environment variable for CI/CD or shared machines where no human is present to complete a browser login.
Q: Can I stop the agent from writing or deleting secrets?
A: Yes — pass --read-only in the server's args. This disables write operations at the server level regardless of what the underlying token would otherwise permit.
Q: Do --project and --config fully sandbox the agent to one environment?
A: They narrow scope as a convenience, but Doppler's documentation doesn't present them as a guaranteed security boundary. The token's own permissions remain the real enforcement point — scope the token itself if you need a hard guarantee.