Heroku MCP Server Cursor IDE Setup (2026)

How do you connect Heroku to Cursor? Install the Heroku CLI (v10.8.1+), then add a heroku entry to ~/.cursor/mcp.json that runs heroku mcp:start — this reuses your existing CLI login, so there's no API key to generate or store. Once it's running, Cursor can list your apps, scale dynos, provision add-ons, tail logs, and run read/write queries against Heroku Postgres, all from chat.

Heroku's MCP server is unusual among the platform integrations on this site: it's a thin wrapper around the Heroku CLI rather than a separate API client, so its permissions are exactly your CLI's permissions, and the fastest setup path (heroku mcp:start) needs no secret at all. That also means anything the CLI can do to a production app — restart dynos, scale to zero, run a destructive SQL statement through pg_psql — the AI can do too, without a confirmation dialog unless your client adds one.

What the Heroku MCP Server Can Do

Once connected, typical prompts include:

The Postgres tools are the deepest part of the surface — pg_psql, pg_ps, pg_locks, pg_outliers, and pg_kill mirror the actual heroku pg CLI subcommands, so if you already know those commands, the MCP prompts map onto them directly.

Prerequisites

Method 1: heroku mcp:start (Recommended — No API Key to Manage)

This is the setup Heroku recommends. It launches the MCP server using your current CLI session, so there's nothing to generate, paste, or accidentally leak in a config file.

Add this to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "heroku": {
      "command": "heroku mcp:start"
    }
  }
}

Restart Cursor, then check View → Output → MCP to confirm it started. If you're not logged in to the CLI (heroku whoami fails), the server will fail to authenticate the same way any heroku command would — run heroku login first.

The tradeoff: this ties the MCP server to whatever account is currently logged into your CLI on that machine. If you switch Heroku accounts locally (heroku login again under a different user), every Cursor session using this config switches with it — there's no way to pin the MCP connection to a specific account independent of your CLI's active session.

Method 2: npx with HEROKU_API_KEY (For a Scoped, Portable Credential)

Use this method if you want the MCP connection independent of whichever account happens to be logged into the CLI locally — for example, a CI-adjacent dev box, or a shared machine where you don't want Cursor silently following CLI account switches.

Generate the API Key

Pick one:

heroku authorizations:create

This creates a new authorization scoped for this purpose. Or reuse your current CLI session's token:

heroku auth:token

You can also generate one from the Heroku Dashboard under Account Settings → Applications → Authorizations.

Add to Cursor's mcp.json

{
  "mcpServers": {
    "heroku": {
      "command": "npx",
      "args": ["-y", "@heroku/mcp-server"],
      "env": {
        "HEROKU_API_KEY": "<YOUR_HEROKU_AUTH_TOKEN>"
      }
    }
  }
}

Neither heroku authorizations:create nor the Dashboard flow lets you scope the token to specific apps or read-only access — a Heroku authorization token carries the same permissions as your account across every app and team you belong to. There's no restricted-key equivalent here the way Stripe or Twilio offer; if you need narrower blast radius, create a dedicated Heroku user with limited team/app access and generate the token from that account instead.

Optional: Adjust the Command Timeout

Long-running commands (a big pg_psql query, a slow deploy) can exceed the server's default 15-second timeout. Set MCP_SERVER_REQUEST_TIMEOUT (in milliseconds) if you're hitting timeouts on legitimate long operations:

{
  "mcpServers": {
    "heroku": {
      "command": "npx",
      "args": ["-y", "@heroku/mcp-server"],
      "env": {
        "HEROKU_API_KEY": "<YOUR_HEROKU_AUTH_TOKEN>",
        "MCP_SERVER_REQUEST_TIMEOUT": "30000"
      }
    }
  }
}

Restart Cursor and Verify

Quit and reopen Cursor completely, then test in chat:

List my Heroku apps

If you see real app names back, the connection is live. Try a read-only Postgres check next:

Show me pg_info for my-app's database

Available Tool Categories

The server groups its tools by area:

The deploy_one_off_dyno Tool Deserves a Second Look

deploy_one_off_dyno runs arbitrary code or commands in a sandboxed one-off dyno with support for file creation, network access, and environment variables. That's genuinely useful for "run this script against production data without setting up a full deploy" — but it's also the single tool in this list with the broadest blast radius: network access from inside your app's environment, plus whatever environment variables that dyno inherits. Before letting an AI reach for this tool unattended, know what config vars and network access the target app's dynos actually have, the same way you'd think twice before handing a contractor SSH access to a one-off box in production.

Practical Workflows

Morning App Health Check

List all my Heroku apps, then for each one show me the dyno formation 
and whether any are in maintenance mode

Debug a Slow Endpoint

My-app's checkout endpoint is slow. Run pg_outliers against my-app's 
database and show me the top 5 most resource-intensive queries.

Scale for a Traffic Spike

Scale my-app's web dynos to 4 and confirm the new dyno count

Investigate a Lock

A write to the orders table is hanging on my-app. Run pg_locks and 
tell me which query is blocking it.

Troubleshooting

heroku mcp:start fails immediately
Confirm you're logged in: heroku whoami. If that fails, run heroku login and try again. Also confirm your CLI version is 10.8.1+; mcp:start doesn't exist in older versions.

Server starts but every tool call returns a permissions error
Your logged-in account (or the account behind HEROKU_API_KEY) doesn't have access to the app you're targeting. Check with heroku apps:info -a <app-name> from the same account to confirm access outside of MCP first.

npx -y @heroku/mcp-server fails to authenticate
Check that HEROKU_API_KEY is set correctly in the env block — a stale token from heroku auth:token becomes invalid if you've logged out and back in since generating it. Re-run heroku authorizations:create for a fresh, dedicated token instead of reusing a session token that can silently rotate out from under you.

Long pg_psql queries or deploys time out
Increase MCP_SERVER_REQUEST_TIMEOUT (milliseconds) — the default is 15000ms, which is short for a large table scan or a multi-minute deploy.

Cursor doesn't pick up account switches after heroku login under a different user
That's expected behavior with the mcp:start method, not a bug — the MCP server always reflects the CLI's currently active session. If you need a connection that's independent of local CLI account state, switch to the npx + HEROKU_API_KEY method instead.

Frequently Asked Questions

Q: Do I need a Heroku API key to use the MCP server?
A: No, not for the recommended method. heroku mcp:start reuses your existing CLI login (heroku login), so there's no key to generate or store. The npx -y @heroku/mcp-server method requires a HEROKU_API_KEY, and is worth using instead when you want the MCP connection independent of whichever account is currently logged into the CLI on that machine.

Q: Can I scope the Heroku MCP connection to just one app, or does it see everything my account can access?
A: It sees everything your account (or the API key's account) can access — apps, teams, and private spaces included. Heroku doesn't currently offer an app-scoped or read-only authorization token the way some other platforms offer restricted API keys. For a narrower blast radius, create a dedicated Heroku user with limited team access and generate the MCP credential from that account.

Q: What's the actual risk if I let an AI use this unsupervised?
A: The same as giving it your Heroku CLI credentials directly — it can scale dynos, transfer app ownership, enable maintenance mode, run arbitrary SQL through pg_psql (including writes), and execute code via deploy_one_off_dyno. None of these are blocked by the MCP server itself; whatever your account or API key can do through the CLI, the AI can do through MCP. Review tool calls before approving them on anything touching a production app.

Q: Does pg_psql let the AI run destructive SQL, not just SELECT queries?
A: Yes. pg_psql executes whatever SQL you (or the AI) give it against the target database, including UPDATE, DELETE, and DROP. It's not a read-only tool. Treat prompts that involve pg_psql against a production database with the same caution you'd apply to pasting SQL directly into a production psql session.

Q: My timeout keeps hitting on a long-running command — what's the fix?
A: Set the MCP_SERVER_REQUEST_TIMEOUT environment variable (in milliseconds) in the npx-based config. The default is 15000ms (15 seconds), which is often too short for a large pg_psql query, a slow deploy_to_heroku call, or a big log tail.

Related Guides

---