Upstash MCP Server Cursor IDE Setup 2026

Upstash runs serverless Redis, QStash (message queues and scheduling), Workflow, and a VM product called Upstash Box. The MCP server gives Cursor a single connection across all four instead of a separate integration per product. Setup is one npx command with your account email and an API key — no separate package install step, and no OAuth flow to click through.

What the Upstash MCP Server Manages

It's genuinely a multi-product server, not a Redis-only tool with the name "Upstash" attached — worth knowing before you assume a prompt about QStash delivery logs needs a separate connection.

Prerequisites

Step 1: Generate an API Key

1. Log into the Upstash Console
2. Go to Account → API Keys
3. Create a key and copy it — you'll need it and your account email for the config

Step 2: Add the Server to mcp.json

{
  "mcpServers": {
    "upstash": {
      "command": "npx",
      "args": [
        "-y",
        "@upstash/mcp-server@latest",
        "--email",
        "YOUR_EMAIL",
        "--api-key",
        "YOUR_API_KEY"
      ]
    }
  }
}

Replace YOUR_EMAIL and YOUR_API_KEY with your real values. Since Cursor 1.0, Upstash also offers a one-click install button on their docs page that writes this block for you.

Step 3: Restart and Verify

Restart Cursor, then in chat:

List my Upstash Redis databases and their region

A real list of your databases confirms the connection.

Read-Only Setup: Use a Readonly API Key

If you want Cursor to inspect your Upstash resources without being able to modify them, generate a readonly API key instead of a full-access one. The server detects the key's permission level at startup and automatically disables every tool that would modify state — this is enforced by the key itself, not by a separate config flag, so a readonly key is the actual security boundary here, not an optional setting.

Optional: Upstash Box API Key

If you're also using Upstash Box (VMs), add a second key either as a CLI flag or an environment variable:

{
  "mcpServers": {
    "upstash": {
      "command": "npx",
      "args": [
        "-y",
        "@upstash/mcp-server@latest",
        "--email",
        "YOUR_EMAIL",
        "--api-key",
        "YOUR_API_KEY",
        "--box-api-key",
        "YOUR_BOX_API_KEY"
      ]
    }
  }
}

Or via env instead of a CLI flag:

{
  "mcpServers": {
    "upstash": {
      "command": "npx",
      "args": ["-y", "@upstash/mcp-server@latest", "--email", "YOUR_EMAIL", "--api-key", "YOUR_API_KEY"],
      "env": {
        "UPSTASH_BOX_API_KEY": "YOUR_BOX_API_KEY"
      }
    }
  }
}

Skip this entirely if you don't use Upstash Box — the base Redis/QStash/Workflow tools work without it.

Practical Workflows

Debugging a stuck QStash message

Show me the delivery status and recent logs for messages sent to 
the /webhooks/order-created endpoint in the last hour — are any stuck retrying?

Checking Redis usage before scaling a feature

What's the current memory usage and request count on my production 
Redis database? I'm about to add a caching layer and want a baseline.

Reviewing a Workflow run that failed

Find the most recent failed run for my order-processing workflow 
and show me which step it failed on and the error it returned.

Gotchas

A readonly key is the real access control — treat it that way. The docs are explicit that the server "automatically disables every tool that would modify state" when started with a readonly key. If a teammate needs write access for one task, generating a temporary full-access key is more auditable than leaving a shared full-access key in a config everyone uses for read-only lookups.

The maintainers' own guidance is to prefer the CLI skill over the MCP server for heavy workflows. Upstash's docs note that for most day-to-day work, driving @upstash/cli through an installed Upstash skill is the preferred path, and the MCP server is positioned more for interactive, chat-driven lookups. If you're scripting something repetitive, check whether the CLI is a better fit before building it around MCP tool calls.

Telemetry is on by default. Add --disable-telemetry to the args array if your org's policy requires opting out.

Troubleshooting

Server starts but every tool call fails with an auth error
Double-check the email matches the account the API key was generated under — a mismatched email/key pair fails auth even if the key itself is valid.

Write operations silently don't appear as available tools
This is expected if the key is a readonly key — the server disables write-capable tools entirely rather than exposing them and failing at call time. Generate a full-access key if you actually need writes.

Box-related prompts fail even though Redis tools work fine
UPSTASH_BOX_API_KEY (or the --box-api-key flag) is a separate credential from the main API key. Confirm it's set if you're trying to provision or inspect a VM.

MCP server not showing up in Cursor at all
Confirm Node.js is on your PATH (which node in terminal), and that you restarted Cursor after editing mcp.json — a running instance doesn't pick up config changes without a restart. See debugging MCP server issues in Cursor for the general checklist.

Frequently Asked Questions

Q: Does the Upstash MCP server only manage Redis, or more?
A: More — it covers Redis, QStash, Workflow, and Upstash Box (VMs) from one connection. A prompt about webhook delivery logs or a failed workflow run doesn't need a separate integration.

Q: How do I make sure Cursor can't modify my Upstash resources?
A: Generate a readonly API key instead of a full-access one. The server detects the key's permission level on startup and disables every write-capable tool automatically — this is enforced by the key, not a config toggle you could forget to set.

Q: Do I need a separate credential for Upstash Box?
A: Yes, if you use it. UPSTASH_BOX_API_KEY (or --box-api-key) is separate from the main account API key. Skip it entirely if you're only using Redis, QStash, or Workflow.

Q: Is there a one-click install, or do I have to hand-edit mcp.json?
A: Since Cursor 1.0, Upstash's docs provide a one-click install button that writes the config block for you. Manual editing of mcp.json still works and is what this guide documents in full.

Q: Should I use the MCP server or the Upstash CLI for automation?
A: For heavy, repetitive automation, Upstash's own guidance favors installing the Upstash skill and driving @upstash/cli directly. The MCP server is the better fit for interactive, chat-driven lookups and one-off changes during development.

Related Guides

---