> ## Documentation Index
> Fetch the complete documentation index at: https://upstash.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP Server
The Upstash MCP server lets your agent manage and debug your Upstash resources directly, across Redis, QStash, Workflow, and [Upstash Box](/box/overall/quickstart).
Find the GitHub repository [here](https://github.com/upstash/mcp).
For most workflows, prefer installing the [Upstash Skill](/agent-resources/skills) and letting your agent drive [`@upstash/cli`](/agent-resources/cli) over running the MCP server.
# Example prompts
## Redis
* "Create a new Redis database in us-east-1"
* "List my databases sorted by memory usage"
* "Give me the schema of how users are stored in this Redis"
* "Find all session keys expiring in the next hour and show me their payloads"
* "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 `@ysfk_0x` in the last 24 hours"
* "Retry the failed workflow run that started 2 hours ago"
* "Summarize what's in the DLQ right now, grouped by error type"
* "Pause the `daily-report` schedule until Monday"
## 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"
# Credentials
Before installing, grab your credentials:
* **Email**: your Upstash account email
* **API Key**: create one at [Upstash Console → Account → API Keys](https://console.upstash.com/account/api)
Readonly API keys are supported. When the server starts with one, it automatically disables every tool that would modify state, such as creating databases, deleting backups, or retrying workflows. Your agent can still read and query your account, but it cannot make changes.
These are passed to the server on startup. The base command every client uses is:
```bash theme={"system"}
npx -y @upstash/mcp-server@latest --email YOUR_EMAIL --api-key YOUR_API_KEY
```
# MCP Clients
The Upstash MCP server works with any MCP-compatible client. If your client isn't listed, check its documentation for how to add a stdio MCP server, then point it at the command above.
Run this command in your terminal. See the [Claude Code MCP docs](https://docs.anthropic.com/en/docs/claude-code/mcp) for more info.
```sh theme={"system"}
claude mcp add --transport stdio 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`, or edit `~/.cursor/mcp.json` directly. You can also scope it to a project by creating `.cursor/mcp.json` in your repo.
Since Cursor 1.0, the one-click install button also works:
[](https://cursor.com/en/install-mcp?name=upstash\&config=eyJjb21tYW5kIjoibnB4IC15IEB1cHN0YXNoL21jcC1zZXJ2ZXJAbGF0ZXN0IC0tZW1haWwgWU9VUl9FTUFJTCAtLWFwaS1rZXkgWU9VUl9BUElfS0VZIn0%3D)
```json theme={"system"}
{
"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](https://docs.windsurf.com/windsurf/cascade/mcp) for more info.
```json theme={"system"}
{
"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](https://opencode.ai/docs/mcp-servers) for more info.
```json theme={"system"}
{
"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](https://developers.openai.com/codex/mcp) for more info.
#### Using the CLI
```sh theme={"system"}
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`):
```toml theme={"system"}
[mcp_servers.upstash]
command = "npx"
args = ["-y", "@upstash/mcp-server@latest", "--email", "YOUR_EMAIL", "--api-key", "YOUR_API_KEY"]
startup_timeout_sec = 20
```
If you see startup timeout errors, increase `startup_timeout_sec` to `40`.
Add this to your VS Code MCP config file at `.vscode/mcp.json`, or paste it into the `mcp.servers` user setting. See the [VS Code MCP docs](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for more info.
[ 
](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%7B%22name%22%3A%22upstash-mcp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40upstash%2Fmcp-server%40latest%22%5D%7D)
```json theme={"system"}
{
"servers": {
"upstash": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@upstash/mcp-server@latest", "--email", "YOUR_EMAIL", "--api-key", "YOUR_API_KEY"]
}
}
}
```
Add this to your Antigravity MCP config. See the [Antigravity MCP docs](https://antigravity.google/docs/mcp) for more info.
```json theme={"system"}
{
"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](https://modelcontextprotocol.io/quickstart/user) for more info.
```json theme={"system"}
{
"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](https://google-gemini.github.io/gemini-cli/docs/tools/mcp-server.html) for details.
```json theme={"system"}
{
"mcpServers": {
"upstash": {
"command": "npx",
"args": ["-y", "@upstash/mcp-server@latest", "--email", "YOUR_EMAIL", "--api-key", "YOUR_API_KEY"]
}
}
}
```
# Upstash Box API key (optional)
For the MCP to interact with [Upstash Box](/box/overall/quickstart), 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
```json theme={"system"}
{
"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
```json theme={"system"}
{
"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"
}
}
}
}
```
# 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.