Lets an AI agent manage and debug Upstash resources including Redis, QStash, Workflow, Vector, Search, Box, and Blob.
Also known as upstash/mcp-server, @upstash/mcp-server
- Stars
- 61
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 0.4.0
- Last commit
- Nov 4, 2026
- License
- MIT
What is Upstash MCP?
Upstash lets an AI agent manage and debug Upstash resources including Redis, QStash, Workflow, Vector, Search, Box, and Blob.
Summary generated from the project's README
About Upstash MCP server
Managing and debugging Upstash resources directly from an AI agent is what this server enables. It provides a way for developers to interact with various services including Redis, QStash, Workflow, Vector, Search, Box, and Blob. By connecting to an MCP-compatible client, an agent can perform administrative tasks or inspect logs across your entire Upstash infrastructure.
Users can set up this server locally using npx with an email and API key, or use the remote version which utilizes OAuth for authentication. For automated environments like CI, the remote server supports a Developer API key via basic authorization. The server also supports readonly API keys, which automatically restricts the agent to querying data and logs without allowing any state-modifying actions like creating databases or deleting backups.
What you can do with it
- 1Provision temporary databasesAn agent can spin up a free Redis instance for testing purposes without requiring a full account setup.
- 2Debug webhook failuresYou can ask an AI to investigate why specific webhooks are failing by examining QStash logs.
- 3Manage workflow executionAn agent can identify and retry specific failed workflow runs from earlier in the day.
- 4Monitor database performanceDevelopers can request summaries of throughput spikes or memory usage across their Redis databases.
Written from the project's README. Every use case is checked against a quote from it.
How to install Upstash MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Upstash MCP in Claude Code
$ claude mcp add --env 'UPSTASH_API_KEY=<YOUR_UPSTASH_API_KEY>' --env 'UPSTASH_EMAIL=<UPSTASH_EMAIL>' --env 'UPSTASH_BOX_API_KEY=<YOUR_UPSTASH_BOX_API_KEY>' mcp-server -- npx -y @upstash/mcp-serverInstall Upstash MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"mcp-server": {
"command": "npx",
"args": [
"-y",
"@upstash/mcp-server"
],
"env": {
"UPSTASH_API_KEY": "<YOUR_UPSTASH_API_KEY>",
"UPSTASH_EMAIL": "<UPSTASH_EMAIL>",
"UPSTASH_BOX_API_KEY": "<YOUR_UPSTASH_BOX_API_KEY>"
}
}
}
}Install Upstash MCP in VS Code
.vscode/mcp.json
{
"servers": {
"mcp-server": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@upstash/mcp-server"
],
"env": {
"UPSTASH_API_KEY": "<YOUR_UPSTASH_API_KEY>",
"UPSTASH_EMAIL": "<UPSTASH_EMAIL>",
"UPSTASH_BOX_API_KEY": "<YOUR_UPSTASH_BOX_API_KEY>"
}
}
}
}Install Upstash MCP in VS Code CLI
$ code --add-mcp '{"name":"mcp-server","type":"stdio","command":"npx","args":["-y","@upstash/mcp-server"],"env":{"UPSTASH_API_KEY":"<YOUR_UPSTASH_API_KEY>","UPSTASH_EMAIL":"<UPSTASH_EMAIL>","UPSTASH_BOX_API_KEY":"<YOUR_UPSTASH_BOX_API_KEY>"}}'Install Upstash MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"mcp-server": {
"command": "npx",
"args": [
"-y",
"@upstash/mcp-server"
],
"env": {
"UPSTASH_API_KEY": "<YOUR_UPSTASH_API_KEY>",
"UPSTASH_EMAIL": "<UPSTASH_EMAIL>",
"UPSTASH_BOX_API_KEY": "<YOUR_UPSTASH_BOX_API_KEY>"
}
}
}
}Install Upstash MCP in Codex
$ codex mcp add mcp-server --env 'UPSTASH_API_KEY=<YOUR_UPSTASH_API_KEY>' --env 'UPSTASH_EMAIL=<UPSTASH_EMAIL>' --env 'UPSTASH_BOX_API_KEY=<YOUR_UPSTASH_BOX_API_KEY>' -- npx -y @upstash/mcp-serverInstall Upstash MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.mcp-server] command = "npx" args = ["-y", "@upstash/mcp-server"] [mcp_servers.mcp-server.env] UPSTASH_API_KEY = "<YOUR_UPSTASH_API_KEY>" UPSTASH_EMAIL = "<UPSTASH_EMAIL>" UPSTASH_BOX_API_KEY = "<YOUR_UPSTASH_BOX_API_KEY>"
Install Upstash MCP in Gemini CLI
$ gemini mcp add -s user -e 'UPSTASH_API_KEY=<YOUR_UPSTASH_API_KEY>' -e 'UPSTASH_EMAIL=<UPSTASH_EMAIL>' -e 'UPSTASH_BOX_API_KEY=<YOUR_UPSTASH_BOX_API_KEY>' mcp-server npx -- -y @upstash/mcp-serverInstall Upstash MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"mcp-server": {
"command": "npx",
"args": [
"-y",
"@upstash/mcp-server"
],
"env": {
"UPSTASH_API_KEY": "<YOUR_UPSTASH_API_KEY>",
"UPSTASH_EMAIL": "<UPSTASH_EMAIL>",
"UPSTASH_BOX_API_KEY": "<YOUR_UPSTASH_BOX_API_KEY>"
}
}
}
}Needs a key before it starts
Started on 16 Nov 2026 with no keys, it stopped and asked for one, so a client sees no tools until you set the variables above.
Configuration
UPSTASH_API_KEYRequiredSecretUpstash Developer API key (create one at https://console.upstash.com/account/api).
UPSTASH_EMAILRequiredEmail address of your Upstash account.
UPSTASH_BOX_API_KEYSecretUpstash Box API key for Box-related tools.
Automated checks
Ran Nov 12, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHubUpstash MCP Server
[!IMPORTANT] This local (stdio) server is no longer maintained. Use the remote Upstash MCP server at
https://mcp.upstash.com/mcpinstead.The remote server signs you in with OAuth, so there is no API key to paste into a config file, and it covers more of Upstash: Redis, QStash, Workflow, Vector, Search, Box and Blob. For headless setups such as CI, it also accepts a Developer API key as
Authorization: Basic base64(email:api_key).claude mcp add --scope user --transport http upstash https://mcp.upstash.com/mcpSetup: upstash.com/docs/agent-resources/overview. Tools and authentication: upstash.com/docs/agent-resources/mcp.
The Upstash MCP server lets your agent manage and debug your Upstash resources directly, across Redis, QStash, Workflow, and Upstash Box.
[!TIP] For most workflows, prefer installing the Upstash Skill and letting your agent drive
@upstash/cliover running the MCP server.
[!TIP] If you are an AI agent and just need a Redis DB to use or experiment with, you don't need an account at all — call the
redis_database_start_freetool, or send a POST request tohttps://upstash.com/start-redisdirectly. It's free, no signup, and the response is markdown with credentials and a quickstart. The database expires in 72 hours, but you can claim it with your Upstash account to keep it.Pass
user_agentto identify yourself (e.g.claude-code,cursor,codex,opencode); the tool forwards it as theUser-Agentheader. Calling the endpoint directly, send the same header yourself, plus a fresh UUIDv4 asIdempotency-Key:curl -X POST -H "Idempotency-Key: <uuidv4>" -H "User-Agent: <your-agent-name>" https://upstash.com/start-redis
Quickstart
You'll need your Upstash account email and an API key — create one at Upstash Console → Account → API Keys.
The Upstash MCP server works with any MCP-compatible client. If your client isn't listed below, check its documentation for how to add a stdio MCP server, then point it at the base command:
npx -y @upstash/mcp-server@latest --email YOUR_EMAIL --api-key YOUR_API_KEY
[!NOTE] Readonly API keys are supported. When the server starts with one, it automatically disables every tool that would modify state (creating databases, deleting backups, retrying workflows, etc.). Your agent can still read and query your account — including Redis, QStash logs, schedules, and Workflow logs — but it cannot make changes. Upstash Box tools are not available with a readonly key.
Run this command in your terminal. See the Claude Code MCP docs for more info.
claude mcp add --scope user upstash -- npx -y @upstash/mcp-server@latest --email YOUR_EMAIL --api-key YOUR_API_KEY
Go to Settings → Cursor Settings → MCP → Add new global MCP server.
Pasting the following configuration into your Cursor ~/.cursor/mcp.json file is the recommended approach. You may also install in a specific project by creating .cursor/mcp.json in your project folder. See the Cursor MCP docs for more info.
Since Cursor 1.0, you can click the install button below for instant one-click installation. Replace YOUR_EMAIL and YOUR_API_KEY with your real values before confirming.
{
"mcpServers": {
"upstash": {
"command": "npx",
"args": [
"-y",
"@upstash/mcp-server@latest",
"--email",
"YOUR_EMAIL",
"--api-key",
"YOUR_API_KEY"
]
}
}
}
Add this to your Windsurf MCP config file at ~/.codeium/windsurf/mcp_config.json. See the Windsurf MCP docs for more info.
{
"mcpServers": {
"upstash": {
"command": "npx",
"args": [
"-y",
"@upstash/mcp-server@latest",
"--email",
"YOUR_EMAIL",
"--api-key",
"YOUR_API_KEY"
]
}
}
}
Add this to your OpenCode configuration file (~/.config/opencode/opencode.json or a project-level opencode.json). See the OpenCode MCP docs for more info.
{
"mcp": {
"upstash": {
"type": "local",
"command": [
"npx",
"-y",
"@upstash/mcp-server@latest",
"--email",
"YOUR_EMAIL",
"--api-key",
"YOUR_API_KEY"
],
"enabled": true
}
}
}
See the OpenAI Codex MCP docs for more info.
Using the CLI
codex mcp add upstash -- npx -y @upstash/mcp-server@latest --email YOUR_EMAIL --api-key YOUR_API_KEY
Manual configuration
Add this to your Codex config file (~/.codex/config.toml or .codex/config.toml):
[mcp_servers.upstash]
command = "npx"
args = ["-y", "@upstash/mcp-server@latest", "--email", "YOUR_EMAIL", "--api-key", "YOUR_API_KEY"]
startup_timeout_sec = 20
[!NOTE] If you see startup timeout errors, increase
startup_timeout_secto40.
Click to install — VS Code will prompt for your email and API key (stored in its secret storage):
Or add this to .vscode/mcp.json (or your user mcp.servers setting). Using inputs with promptString means your API key is prompted once and kept in VS Code's secret storage instead of sitting in the config file. See the VS Code MCP docs for more info.
{
"inputs": [
{ "type": "promptString", "id": "email", "description": "Upstash email" },
{ "type": "promptString", "id": "apiKey", "description": "Upstash API key", "password": true }
],
"servers": {
"upstash": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@upstash/mcp-server@latest",
"--email",
"${input:email}",
"--api-key",
"${input:apiKey}"
]
}
}
}
Add this to your Antigravity MCP config. See the Antigravity MCP docs for more info.
{
"mcpServers": {
"upstash": {
"command": "npx",
"args": [
"-y",
"@upstash/mcp-server@latest",
"--email",
"YOUR_EMAIL",
"--api-key",
"YOUR_API_KEY"
]
}
}
}
Open Claude Desktop's developer settings and edit claude_desktop_config.json. See the Claude Desktop MCP docs for more info.
{
"mcpServers": {
"upstash": {
"command": "npx",
"args": [
"-y",
"@upstash/mcp-server@latest",
"--email",
"YOUR_EMAIL",
"--api-key",
"YOUR_API_KEY"
]
}
}
}
Open the Gemini CLI settings file at ~/.gemini/settings.json and add Upstash to mcpServers. See Gemini CLI Configuration for details.
{
"mcpServers": {
"upstash": {
"command": "npx",
"args": [
"-y",
"@upstash/mcp-server@latest",
"--email",
"YOUR_EMAIL",
"--api-key",
"YOUR_API_KEY"
]
}
}
}
Example prompts
Redis
- "Start a free temporary Redis I can experiment with"
- "Create a new Redis database in us-east-1"
- "List my databases sorted by memory usage"
- "Update the user schema by pulling from Redis"
- "Create a backup of this db, then clear it"
- "Show me throughput spikes during the last 7 days"
QStash & Workflow
- "Check the QStash logs and figure out why my webhook keeps failing"
- "Find failed workflow runs for user
@admintoday" - "Retry the failed workflow run that started 2 hours ago"
- "Summarize what's in the DLQ right now, grouped by error type"
- "Pause the schedules that are throwing errors"
Upstash Box
- "Spin up a Box, clone this repo, and run the tests"
- "Snapshot this Box and create 5 copies from it, assign each one a GitHub issue"
- "My Box keeps failing to start, check the logs and tell me what's wrong"
Using a Box as your workspace
A Box is a remote Linux container with its own filesystem. The Box tools let an agent work inside one while the agent itself keeps running on your machine: files through box_read / box_write / box_edit, commands through box_exec, git and search through box_git, and a running server through box_preview. box_upload copies files into the Box from the machine running the MCP server, which is how uncommitted local work gets in — a clone only brings what you have pushed. With the usual stdio setup the server runs on your own machine, so those are your paths; if you run it remotely with --transport http, it reads the server host's filesystem instead, not yours.
Box tools need a Box API key, which is a different credential from your Upstash account API key — the two are not interchangeable. The install command at the top of this README does not include one, so pass --box-api-key as well or the first Box call will fail:
claude mcp add --scope user upstash -- npx -y @upstash/mcp-server@latest \
--email YOUR_EMAIL --api-key YOUR_API_KEY --box-api-key YOUR_BOX_API_KEY
See Upstash Box API key for the environment-variable form and where to get the key.
If you only use Upstash Box, you can start the server with --box-api-key alone and no account credentials. Redis, QStash and Workflow tools are unavailable in that mode.
Create the workspace once and reuse its id:
- "Create a Box with clone_repo https://github.com/me/my-app, no agent, then wait until the repo is there"
- "In that Box, run the tests and fix whatever fails"
- "Commit on a new branch in the Box and open a PR"
A create returns while the container is still coming up, and clone_repo starts cloning only once the Box reports idle, so give it a moment before the first read.
The one thing to know: your agent's own Read, Write, Edit, Bash, Glob and Grep tools still act on your machine. Nothing stops it from reading a local file and writing the change into the Box, and neither side reports the mismatch. The server sends guidance at startup and every Box tool says which machine it touches, but if you want the boundary enforced rather than suggested, add a CLAUDE.md to the project you're driving from:
# Workspace
The workspace for this project is an Upstash Box, not this directory.
- Use `box_read`, `box_write` and `box_edit` for files; `box_exec` for commands;
`box_git` for git and for search (`git grep`, `git ls-files`).
- Do not use Read, Write, Edit, Bash, Glob or Grep for project files — they act
on this machine. Searching locally finds the wrong tree, or nothing at all.
- The one exception is `box_upload`: it reads paths on this machine on purpose,
to copy local files into the Box.
- The box id for this project is: <paste it here>
Upstash Box API key (optional)
For the MCP to interact with Upstash Box, the agent needs your Box API key. By default you have to paste it into the chat (or keep it in a .env) every time the agent runs a Box tool. To avoid this, you can wire the key into the MCP setup itself so the server picks it up automatically on startup.
You can pass it in two ways.
CLI flag
{
"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"
]
}
}
}
Environment variable
{
"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"
}
}
}
}
Debugging
If the server is misbehaving or a tool keeps failing, enable verbose logging with the --debug flag:
{
"mcpServers": {
"upstash": {
"command": "npx",
"args": [
"-y",
"@upstash/mcp-server@latest",
"--email",
"YOUR_EMAIL",
"--api-key",
"YOUR_API_KEY",
"--debug"
]
}
}
}
Every internal event is then written to stderr, which your MCP client surfaces in its own log viewer. Share the relevant snippet when reporting an issue on GitHub.
Telemetry
The server sends anonymous diagnostic info to Upstash with each request: the MCP server SDK version, your runtime version (Node, Bun, etc.), and basic platform info (OS and architecture). No account data, tool arguments, or results are collected. To opt out, add --disable-telemetry to the args.
Development
Clone the project and run:
bun i
bun run watch
This continuously builds the project and watches for changes.
To run the built server standalone (uses .env for credentials) and smoke-test it before publishing:
bun i # ensure deps are current
bun run build
# stdio (default) — waits for an MCP client to speak JSON-RPC on stdin:
bun dist/index.js
# or HTTP transport, to poke it manually on a port:
bun dist/index.js --transport http --port 3000
For testing, create a .env file in the project root:
UPSTASH_EMAIL=<UPSTASH_EMAIL>
UPSTASH_API_KEY=<UPSTASH_API_KEY>
# Optional, for Box tools:
UPSTASH_BOX_API_KEY=<UPSTASH_BOX_API_KEY>
To install the local MCP server into Claude Code:
claude mcp add --transport stdio upstash -- bun --watch dist/index.js --debug
To tail logs from the MCP server in real time:
bun run logs
Upstash MCP questions
How do I add Upstash MCP to Claude Code?
Run claude mcp add --env 'UPSTASH_API_KEY=<YOUR_UPSTASH_API_KEY>' --env 'UPSTASH_EMAIL=<UPSTASH_EMAIL>' --env 'UPSTASH_BOX_API_KEY=<YOUR_UPSTASH_BOX_API_KEY>' mcp-server -- npx -y @upstash/mcp-server in your terminal. Add --scope user to make it available in every project.
How do I add Upstash MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
Is the local Upstash MCP server still maintained?
No, the local stdio server is no longer maintained. You should use the remote Upstash MCP server instead.
Can I use a readonly API key with this server?
Yes, readonly keys are supported. The server will automatically disable tools that modify state, though your agent can still read and query your account.
Do I need an account to experiment with Redis?
No, you can call the redis_database_start_free tool to get a free temporary database without signing up.