Heroku Platform MCP Server
Connect AI assistants to the Heroku Platform to manage applications, databases, dynos, pipelines, and infrastructure through natural language commands.
Overview
This skill enables AI assistants to interact with Heroku Platform resources using the Model Context Protocol (MCP). It provides comprehensive tools for application management, deployment, database operations, and infrastructure control.
Prerequisites
Before using this skill, ensure:
1. **Heroku CLI v10.8.1 or higher** is installed globally
- Install/upgrade: https://devcenter.heroku.com/articles/heroku-cli
- Verify version: `heroku --version`
2. **Authentication** is configured (choose one method):
- **Recommended**: Use `heroku mcp:start` command (leverages existing CLI auth)
- **Alternative**: Set `HEROKU_API_KEY` environment variable with auth token
Installation
Method 1: Using Heroku CLI (Recommended)
Configure your AI client to use the Heroku MCP server via CLI authentication:
```json
{
"mcpServers": {
"heroku": {
"command": "heroku mcp:start"
}
}
}
```
**Benefits:**
No API key management requiredUses existing Heroku CLI authenticationMore secure (no exposed credentials)Method 2: Using npx with API Key
First, generate a Heroku authorization token:
```bash
Create new token
heroku authorizations:create
Or retrieve existing token
heroku auth:token
```
Then configure your client:
```json
{
"mcpServers": {
"heroku": {
"command": "npx",
"args": ["-y", "@heroku/mcp-server"],
"env": {
"HEROKU_API_KEY": "<YOUR_HEROKU_AUTH_TOKEN>"
}
}
}
}
```
Method 3: Smithery (Claude Desktop)
```bash
npx -y @smithery/cli install @heroku/heroku-mcp-server --client claude
```
Available Capabilities
Application Management
**List apps**: View all apps (filter by personal/team/space)**Get app info**: Detailed app configuration, dynos, add-ons**Create app**: New apps with region/team/space settings**Rename app**: Change app names**Transfer app**: Move ownership to user/team**Deploy**: Deploy projects with `app.json` configuration**One-off dynos**: Execute code in sandboxed environmentsProcess & Dyno Management
**List dynos**: View all running dynos**Scale**: Adjust dyno count or resize dynos**Restart**: Restart specific dynos or process typesDatabase Operations (PostgreSQL)
**Execute SQL**: Run queries with `pg_psql`**View info**: Database details and configuration**Monitor queries**: Active queries and execution details**Manage locks**: View and resolve blocking transactions**Identify bottlenecks**: Find resource-intensive queries**Credentials**: Manage database access**Kill processes**: Terminate specific database processes**Maintenance**: View maintenance schedules**Backups**: Manage backup schedules and restoration**Upgrades**: Upgrade PostgreSQL versionsAdd-ons
**List add-ons**: View all or app-specific add-ons**Get add-on info**: Detailed add-on information**Provision add-ons**: Create new add-ons for appsPipeline Management
**Create pipelines**: Set up deployment pipelines**Promote apps**: Move apps through pipeline stages**List pipelines**: View available pipelines**Pipeline info**: Get detailed pipeline informationMaintenance & Monitoring
**Maintenance mode**: Enable/disable maintenance windows**View logs**: Application log streamingTeam & Space Management
**List teams**: View team memberships**List spaces**: View available private spacesUsage Instructions
When a user requests Heroku operations, follow these steps:
1. **Verify Prerequisites**
- Confirm Heroku CLI is installed (v10.8.1+)
- Check authentication is configured
- Ensure MCP server is properly configured in the client
2. **Understand the Request**
- Identify the specific Heroku resource (app, database, dyno, etc.)
- Determine the operation type (create, read, update, delete, scale)
- Note any specific parameters (app name, region, plan, etc.)
3. **Execute Operations**
- Use the appropriate tool from the available capabilities
- For multi-step operations, break down into sequential steps
- Always verify app/resource names before destructive operations
4. **Handle Responses**
- Parse JSON responses from Heroku API
- Present information in user-friendly format
- Suggest next steps or related operations when relevant
5. **Error Handling**
- If authentication fails, guide user to verify CLI setup or API key
- For resource not found errors, suggest listing available resources
- For permission errors, check team/space access requirements
Examples
Example 1: Deploy Application
```
User: Deploy my project to Heroku
Assistant: I'll deploy your project to Heroku.
Using deploy_to_heroku toolCreating new app in US regionPushing code and buildingSetting up environment variablesDeployment complete! App URL: https://myapp-12345.herokuapp.com```
Example 2: Scale Dynos
```
User: Scale my web dynos to 3 instances
Assistant: I'll scale your web dynos.
Using ps_scale tool for app "myapp"Scaling web dynos from 1 to 3Updated: web=3:standard-1x```
Example 3: Database Query
```
User: Show me the top 10 users by signup date
Assistant: I'll query your database.
Using pg_psql toolExecuting: SELECT * FROM users ORDER BY created_at DESC LIMIT 10Results: [formatted table output]```
Example 4: Pipeline Promotion
```
User: Promote staging to production
Assistant: I'll promote your staging app to production.
Using pipelines_promote toolPromoting from staging to production stageDeployment in progress...Production updated successfully```
Configuration Options
Environment Variables
**HEROKU_API_KEY** (required for npx method)
Your Heroku authorization tokenNot needed when using `heroku mcp:start`**MCP_SERVER_REQUEST_TIMEOUT** (optional)
Timeout for command execution in millisecondsDefault: 15000 (15 seconds)Example: Set to 30000 for longer operations```json
{
"env": {
"HEROKU_API_KEY": "<token>",
"MCP_SERVER_REQUEST_TIMEOUT": "30000"
}
}
```
Important Notes
**Platform Support**: Works with Common Runtime, Cedar Private/Shield Spaces, and Fir Private Spaces**Security**: Prefer `heroku mcp:start` to avoid exposing API keys in configuration files**Rate Limits**: Respect Heroku API rate limits; batch operations when possible**Destructive Operations**: Always confirm before deleting apps, databases, or performing irreversible actions**Logs**: Use streaming logs for real-time debugging; specify time ranges for historical logsTroubleshooting
**Server not connecting:**
Verify Heroku CLI version: `heroku --version`Check authentication: `heroku auth:whoami`Restart your AI client after configuration changes**Timeout errors:**
Increase `MCP_SERVER_REQUEST_TIMEOUT` valueCheck network connectivity to Heroku APIVerify app/resource exists and is accessible**Permission denied:**
Confirm you have access to the team/spaceCheck if app requires specific role permissionsVerify API key has necessary scopes