Aiven MCP server for managed services

Aiven MCP is a Model Context Protocol (MCP) server that lets AI assistants such as Cursor and Claude Code create and manage Aiven services, including PostgreSQL®, Apache Kafka®, and OpenSearch®. For PostgreSQL and Kafka, you can also work with the data in your services. You can view service status, metrics, logs, and configuration, and manage services and plans.

To use Aiven MCP, you need an Aiven account.

Use read-only mode to restrict MCP tools to viewing services and other resources. You can enable it in your client or as an organization policy. You can also limit tools to specific services to keep the assistant focused.

What Aiven MCP can do

After you connect an AI assistant to Aiven MCP, you can use natural language to work with your Aiven resources.

• View resources: List projects, services, and integrations, and check the status, plan, and cloud region of a service.
• Manage services: Create, update, and delete services such as Aiven for PostgreSQL®, Aiven for Apache Kafka®, and Aiven for OpenSearch®. Change service plans and compare plans and pricing.
• Troubleshoot services: Review service metrics, logs, and configuration.
• Work with PostgreSQL: Run read-only SQL queries, find slow queries and missing indexes, and manage extensions such as pgvector. For example: Which queries on my database are slowest, and what index would help?
• Work with Apache Kafka: List topics and consumer groups, inspect consumer lag, produce and read messages, inspect schemas, and manage Kafka Connect connectors. For example: Is any consumer group behind on my orders topic?
• Deploy applications: Deploy applications to Aiven Runtime.
• Search the Aiven documentation: Ask questions about Aiven and get answers from the documentation.

Read-only mode restricts these tools to viewing resources.

Prerequisites

• An Aiven account. Aiven MCP is included with your account at no extra cost.
• An MCP-compatible client, such as Cursor, Claude Code, Claude Desktop, VS Code, or Gemini CLI.
• MCP connections enabled for your organization. If you created your Aiven account, you're the organization admin and can enable them in the Aiven Console: click Admin > Authentication > Allow MCP connections. Otherwise, ask your organization admin to enable them.

Authentication uses OAuth 2.0 with PKCE. When you authenticate a client for the first time, your browser opens so you can sign in and authorize MCP access. This is usually a one-time setup step per client.

note

Aiven owns the aiven.live domain and operates the hosted MCP server at mcp.aiven.live. The server uses the Aiven API at api.aiven.io for authorization.

Install Aiven MCP

Claude Code

1. Open a terminal.

2. Choose your options, then run the generated command:

   Services

   AllPostgreSQLKafkaOpenSearchIntegrations

   AccessRead-onlyRead-only, plus specific writesFull access

   Read and write. The assistant can create, modify, and delete.

   ⚠ With full access, the assistant can create, modify, and delete services and data. Review security and responsibility.

   Advanced settings

   DevelopmentAllow connection credentials (development only)

   MarketplaceNone (Aiven)AWS MarketplaceAzure MarketplaceGoogle Cloud Marketplace

   Select your marketplace only if you subscribed to Aiven through AWS, Azure, or Google Cloud Marketplace. This helps you sign in to the correct console.

   claude mcp add --transport http aiven "https://mcp.aiven.live/mcp"

3. Run claude to start Claude Code.

4. Run /mcp, select aiven, and authenticate in your browser when prompted.

5. Test the connection with a prompt such as List my Aiven projects. and approve the tool execution if prompted.

For more information, see the Claude Code MCP documentation.

Cursor

For one-click installation:

Add to Cursor

To add the server manually:

1. In your project root, create or edit the .cursor/mcp.json file.
2. Choose your options below, then copy the generated configuration into the file:

Services

AllPostgreSQLKafkaOpenSearchIntegrations

AccessRead-onlyRead-only, plus specific writesFull access

Read and write. The assistant can create, modify, and delete.

⚠ With full access, the assistant can create, modify, and delete services and data. Review security and responsibility.

Advanced settings

DevelopmentAllow connection credentials (development only)

MarketplaceNone (Aiven)AWS MarketplaceAzure MarketplaceGoogle Cloud Marketplace

Select your marketplace only if you subscribed to Aiven through AWS, Azure, or Google Cloud Marketplace. This helps you sign in to the correct console.

{
  "mcpServers": {
    "aiven": {
      "type": "http",
      "url": "https://mcp.aiven.live/mcp"
    }
  }
}

3. Save the file.
4. Restart Cursor.
5. Open Settings > Tools & MCP.
6. Select aiven and click Connect.

In Cursor Chat (Cmd+L / Ctrl+L), test the connection with a prompt such as List my Aiven projects. and click Allow if prompted.

For more information, see the Cursor MCP documentation.

Claude Desktop

1. Open the Claude Desktop configuration file. If it does not exist, create it:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Choose your options, then add the generated configuration to the file:

   Services

   AllPostgreSQLKafkaOpenSearchIntegrations

   AccessRead-onlyRead-only, plus specific writesFull access

   Read and write. The assistant can create, modify, and delete.

   ⚠ With full access, the assistant can create, modify, and delete services and data. Review security and responsibility.

   Advanced settings

   DevelopmentAllow connection credentials (development only)

   MarketplaceNone (Aiven)AWS MarketplaceAzure MarketplaceGoogle Cloud Marketplace

   Select your marketplace only if you subscribed to Aiven through AWS, Azure, or Google Cloud Marketplace. This helps you sign in to the correct console.

   {
     "mcpServers": {
       "aiven": {
         "command": "npx",
         "args": [
           "-y",
           "mcp-remote",
           "https://mcp.aiven.live/mcp"
         ]
       }
     }
   }

3. Save the file.

4. Restart Claude Desktop.

5. In a new conversation, test the connection with a prompt such as List my Aiven projects. and click Allow if prompted.

For more information, see the Claude Desktop MCP documentation.

VS Code

note

Requires VS Code 1.102 or later with the GitHub Copilot extension installed and enabled.

1. Open your workspace in VS Code.

2. In the workspace root, create a .vscode directory.

3. In the .vscode directory, create or edit the mcp.json file.

4. Choose your options, then add the generated configuration to the file:

   Services

   AllPostgreSQLKafkaOpenSearchIntegrations

   AccessRead-onlyRead-only, plus specific writesFull access

   Read and write. The assistant can create, modify, and delete.

   ⚠ With full access, the assistant can create, modify, and delete services and data. Review security and responsibility.

   Advanced settings

   DevelopmentAllow connection credentials (development only)

   MarketplaceNone (Aiven)AWS MarketplaceAzure MarketplaceGoogle Cloud Marketplace

   Select your marketplace only if you subscribed to Aiven through AWS, Azure, or Google Cloud Marketplace. This helps you sign in to the correct console.

   {
     "servers": {
       "aiven": {
         "type": "http",
         "url": "https://mcp.aiven.live/mcp"
       }
     }
   }

5. Save the file.

6. Reload VS Code.

7. Open the Command Palette, run MCP: List Servers, and confirm that aiven appears.

8. In Copilot Chat, test the connection with a prompt such as List my Aiven projects. and click Allow if prompted.

For more information, see the VS Code MCP documentation.

Gemini CLI

1. Create or edit the ~/.gemini/settings.json file.

2. Choose your options, then add the generated configuration to the file:

   Services

   AllPostgreSQLKafkaOpenSearchIntegrations

   AccessRead-onlyRead-only, plus specific writesFull access

   Read and write. The assistant can create, modify, and delete.

   ⚠ With full access, the assistant can create, modify, and delete services and data. Review security and responsibility.

   Advanced settings

   DevelopmentAllow connection credentials (development only)

   MarketplaceNone (Aiven)AWS MarketplaceAzure MarketplaceGoogle Cloud Marketplace

   Select your marketplace only if you subscribed to Aiven through AWS, Azure, or Google Cloud Marketplace. This helps you sign in to the correct console.

   {
     "mcpServers": {
       "aiven": {
         "httpUrl": "https://mcp.aiven.live/mcp"
       }
     }
   }

3. Save the file.

4. Run gemini to start the CLI.

5. Run /mcp auth aiven to sign in through your browser.

6. Test the connection with a prompt such as List my Aiven projects. and approve the tool execution if prompted.

Other clients

1. Open your MCP client configuration.

2. Choose your options, then add the generated configuration to your client:

   Services

   AllPostgreSQLKafkaOpenSearchIntegrations

   AccessRead-onlyRead-only, plus specific writesFull access

   Read and write. The assistant can create, modify, and delete.

   ⚠ With full access, the assistant can create, modify, and delete services and data. Review security and responsibility.

   Advanced settings

   DevelopmentAllow connection credentials (development only)

   MarketplaceNone (Aiven)AWS MarketplaceAzure MarketplaceGoogle Cloud Marketplace

   Select your marketplace only if you subscribed to Aiven through AWS, Azure, or Google Cloud Marketplace. This helps you sign in to the correct console.

   {
     "mcpServers": {
       "aiven": {
         "url": "https://mcp.aiven.live/mcp",
         "oauth": {
           "oauthScopes": [
             "projects",
             "services",
             "accounts:read"
           ]
         }
       }
     }
   }

   Most clients use a configuration similar to the preceding example.

3. Save the file and restart your client.

4. In your AI assistant, test the connection with a prompt such as List my Aiven projects. and approve the tool execution if prompted.

Some clients require a transport type, such as "type": "http". If the configuration fails, see your client documentation.

Local installation

Use a local installation if you cannot use OAuth, for example in headless environments. The permissions of your API token apply.

Run the Aiven MCP server locally with npx instead of using the hosted server. You need an Aiven API token to authenticate requests to Aiven. Set AIVEN_READ_ONLY="true" to enable read-only mode.

Set AIVEN_ALLOW_SECRETS="true" to let the AI agent access PostgreSQL and Kafka connection credentials. Use this option only in development environments for non-production services. For more information, see Security and responsibility.

Claude Code

1. Open a terminal.

2. Run the following command, replacing your-token-here with your Aiven API token:

   claude mcp add --scope user aiven-mcp -e AIVEN_TOKEN=your-token-here -e AIVEN_READ_ONLY=false -e AIVEN_ALLOW_SECRETS=false -- npx -y mcp-aiven

3. Run claude to start Claude Code.

4. Run /mcp to verify that the server is registered.

Cursor

1. In your project root, create or edit the .cursor/mcp.json file.

2. Add the following configuration, replacing your-token-here with your Aiven API token:

   {
     "mcpServers": {
       "aiven-mcp": {
         "command": "npx",
         "args": ["-y", "mcp-aiven"],
         "env": {
           "AIVEN_TOKEN": "your-token-here",
           "AIVEN_READ_ONLY": "false",
           "AIVEN_ALLOW_SECRETS": "false"
         }
       }
     }
   }

3. Save the file and restart Cursor.

Claude Desktop

1. Open the Claude Desktop configuration file.

2. Add the following configuration, replacing your-token-here with your Aiven API token:

   {
     "mcpServers": {
       "aiven-mcp": {
         "command": "npx",
         "args": ["-y", "mcp-aiven"],
         "env": {
           "AIVEN_TOKEN": "your-token-here",
           "AIVEN_READ_ONLY": "false",
           "AIVEN_ALLOW_SECRETS": "false"
         }
       }
     }
   }

3. Save the file and restart Claude Desktop.

VS Code

1. In the .vscode directory, create or edit the mcp.json file.

2. Add the following configuration, replacing your-token-here with your Aiven API token:

   {
     "servers": {
       "aiven-mcp": {
         "command": "npx",
         "args": ["-y", "mcp-aiven"],
         "env": {
           "AIVEN_TOKEN": "your-token-here",
           "AIVEN_READ_ONLY": "false",
           "AIVEN_ALLOW_SECRETS": "false"
         }
       }
     }
   }

3. Save the file and reload VS Code.

Other clients

1. Open your MCP client configuration.

2. Add the following configuration, replacing your-token-here with your Aiven API token:

   {
     "mcpServers": {
       "aiven-mcp": {
         "command": "npx",
         "args": ["-y", "mcp-aiven"],
         "env": {
           "AIVEN_TOKEN": "your-token-here"
         }
       }
     }
   }

3. Save the file and restart your client.

Example prompts

After you connect your client, try these prompts in your AI assistant.

1. List your projects:

   List my Aiven projects.

   The assistant lists the projects you have access to. This verifies that the connection works.

2. Ask a question about Aiven:

   How do I find unused Kafka topics with no consumer groups?

   The assistant searches the Aiven documentation and answers in the chat. This prompt works in read-only mode and does not need an existing service.

3. Inspect a service:

   Show me the status and configuration of my Aiven service SERVICE_NAME.

   Replace SERVICE_NAME with the name of an existing service.

4. Create a PostgreSQL service:

   Create a PostgreSQL service in REGION.

   Replace REGION with your preferred cloud region. This prompt requires write access. If read-only mode is on, the assistant cannot create services.

For more examples, see What Aiven MCP can do.

Read-only mode

Read-only mode restricts MCP tools to viewing services and other resources. You cannot create, modify, or delete resources. Read-only mode applies at the organization level and the client level.

To allow only specific write actions, see Limit tool access. An organization-level read-only policy overrides it.

PostgreSQL read queries still work in read-only mode.

Organization level

Organization admins can restrict MCP connections to read-only operations for all users in the organization.

1. In the organization, click Admin > Authentication.
2. Select Restrict MCP connections to read-only operations.

Users cannot override this setting in their client configuration. Write operations fail even if a user configures their client without read-only mode.

For more information, see Set authentication policies for organization users.

Client level

You can enable read-only mode for your client in the installation configuration. The setting applies only to that client and does not change the organization policy. It cannot override an organization-level restriction.

Limit tool access

In the install steps, use the options to limit the tools that your assistant loads:

• Services: Select PostgreSQL, Kafka, or Integrations to load only the tools for those services. Tools for projects and services are always included. Select All to load every tool.
• Access: Select Read-only to block write operations. Select Read-only, plus specific writes to allow only the write actions you choose, such as creating Kafka topics.

An organization-level read-only policy overrides your client settings.

Security and responsibility

important

MCP tools can perform destructive operations on your Aiven services, including creating, modifying, and deleting services, databases, topics, and data.

AI agents run operations from natural language prompts, which can be misinterpreted. Using the Aiven MCP server can result in damage to or loss of data.

Aiven secures the MCP server and data in transit. Your selected AI agent provider determines how the agent uses your data, including whether it uses that data for training. Review the provider's terms before you enable the integration.

Under the shared responsibility model, security and compliance for MCP usage are shared between Aiven and your organization. Aiven secures the platform and API. You are responsible for the following:

• Decide on MCP access. Evaluate whether to enable MCP in your organization and the associated risks.
• Control access. Scope API tokens to the minimum permissions needed and rotate them regularly.
• Review AI agent actions. Review actions before they run, especially write or delete operations on production resources.
• Limit write access. Use read-only mode at the organization level for all users, or at the client level for an individual client.
• Keep credentials off in production. The Allow connection credentials option (allow_secrets=true) returns PostgreSQL and Kafka connection credentials, including URIs, passwords, and certificates, to the AI agent. Use it only for development with non-production services that do not hold sensitive data.

The Aiven MCP server can also connect directly to PostgreSQL services running in a private VPC.

Related pages

• Aiven MCP use cases: Examples of what you can do with Aiven MCP
• Aiven MCP announcement: Overview of what Aiven MCP can do
• PostgreSQL MCP server blog post: Use Aiven MCP with PostgreSQL
• Kafka MCP blog post: Use Aiven MCP with Apache Kafka