Aiven-Open/mcp-aiven

Aiven MCP Server

一个用于 Aiven 云数据平台的 Model Context Protocol (MCP) server。

直接通过 Claude、Cursor 和 VS Code Copilot 等 AI 助手管理 PostgreSQL、Apache Kafka、应用程序以及其他 Aiven 服务。

> [!WARNING]
> 谨慎使用。 此 MCP server 可以代表您创建、修改和删除 Aiven 服务及数据。AI agent 可能会根据其对您提示词的理解执行破坏性操作（如删除数据库、删除服务、发送消息）。您对通过此工具执行的操作负全部责任。
>
> 权限： 访问权限由与认证账户关联的 Aiven 用户权限控制。MCP server 只能执行您的 Aiven 用户被允许的操作。
>
> AI Agent 安全性： AI agent 可能需要访问凭据（数据库连接字符串、streaming tokens）才能代表您执行操作。请审查 agent 的操作，尤其是在生产环境中。在授予 AI agent 访问敏感资源的权限之前，请遵循您组织的安全策略并进行风险评估。

Quick Start

选项 1：远程（由 Aiven 托管）

MCP server 托管在 https://mcp.aiven.live/mcp。您的 MCP client 将提示您在 Aiven 上进行授权。

Claude Code

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


或手动添加到 Cursor MCP 设置：

{
  "mcpServers": {
    "aiven-mcp": {
      "url": "https://mcp.aiven.live/mcp"
    }
  }
}

在工作区的 .vscode/mcp.json 中添加：

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

在 URL 中添加 ?read_only=true 即可启用只读模式。所有写操作将被排除在 MCP 之外：

{
  "mcpServers": {
    "aiven-mcp": {
      "url": "https://mcp.aiven.live/mcp?read_only=true"
    }
  }
}

通过在 URL 中添加 ?services_scope= 来减少暴露给 AI agent 的工具范围。当你仅使用部分 Aiven 服务并希望保持 agent 的上下文聚焦时，此功能非常有用。多个值请使用逗号分隔。core（项目/服务发现）始终被隐式包含。

有效作用域：all、core、pg、kafka、application、integrations。使用 all 可显式加载所有工具（与省略该参数效果相同）。all 不能与其他作用域组合使用。

{
  "mcpServers": {
    "aiven-mcp": {
      "url": "https://mcp.aiven.live/mcp?services_scope=kafka"
    }
  }
}

https://mcp.aiven.live/mcp?services_scope=pg&read_only=true

当 read_only=true 时，添加 ?write_allowlist= 可在保持其他所有内容只读的同时，重新启用特定的写入工具。这在您需要大部分只读访问但仍需允许某项写入操作（例如创建 Kafka topics）时非常有用。多个工具名称请使用逗号分隔。当 read_only 未启用时，此项将被忽略。

https://mcp.aiven.live/mcp?read_only=true&write_allowlist=aiven_kafka_topic_create

如果您通过云 marketplace 订阅了 Aiven，请将您的 marketplace 添加为路径段，以便登录时使用正确的控制台：

| Marketplace | 路径段 |
| --- | --- |
| AWS Marketplace | https://mcp.aiven.live/mcp/aws |
| Azure Marketplace | https://mcp.aiven.live/mcp/azure |
| Google Cloud Marketplace | https://mcp.aiven.live/mcp/gcp |

{
  "mcpServers": {
    "aiven-mcp": {
      "url": "https://mcp.aiven.live/mcp/<marketplace>"
    }
  }
}

选项 2：stdio (本地)

将服务器作为 MCP 客户端的子进程在本地运行。需要 Node.js 18+。

您必须通过 AIVEN_TOKEN 环境变量提供 Aiven API token。在此创建 token。

Claude Code

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

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

• Cursor：Cursor Settings > MCP Servers

• VS Code：工作区中的 .vscode/mcp.json

选项 3：本地开发

运行服务器的本地构建（适用于开发和测试）：

pnpm install && pnpm generate:api-types && pnpm generate && pnpm build && AIVEN_TOKEN="<YOUR_TOKEN>" MCP_TRANSPORT="http" PORT=3000 node dist/index.js

若要将远程部署指向自定义主机（例如您的本地构建），请设置 MCP_HOST：

MCP_HOST=http://localhost:3000 node dist/index.js

生产环境的 HTTP 流量分为两层速率限制：Cloudflare 强制执行基于客户端 IP 的限制（在 Cloudflare 控制面板中配置），而本服务器在 POST /mcp 上针对每个 bearer token 强制执行 MCP_HTTP_RATE_LIMIT_*。

Edge protection 部署

当 EXTRA_PROTECTION=true 时，如果 MCP_EDGE_AUTH_SECRET 与 Cloudflare 注入的 X-Edge-Auth 值不匹配，将导致所有请求返回 403（GET /health 除外）。这两个值分别位于网络两端的环境/配置中，因此唯一的恢复路径是修复 secret 并重新部署或更新 Cloudflare。

请按此顺序启用：1. Cloudflare Transform Rule — 添加一条规则，为发往 MCP origin 的流量设置 X-Edge-Auth（如果用于 PG 工具，还需设置 X-Client-IP）。记录你配置的 secret 值。
2. MCP_EDGE_AUTH_SECRET — 部署服务器，并将此环境变量设置为与 Transform Rule 相同的 secret。暂时将 EXTRA_PROTECTION 保持为空或 false；验证 origin 仍能接收流量。
3. EXTRA_PROTECTION=true — 仅在步骤 1-2 生效且匹配后启用。确认正常的 MCP 请求能够成功，且没有 X-Edge-Auth 的直接 origin 访问被拒绝。
4. Secret rotation — 同时更新 Cloudflare 和 MCP_EDGE_AUTH_SECRET（或短暂将 EXTRA_PROTECTION 设为 false），重新部署，然后重新启用。在 flag 开启时，切勿单独更新其中一方。

如果在启动时 EXTRA_PROTECTION=true 且缺失 MCP_EDGE_AUTH_SECRET，进程将立即报错退出。

在持续拒绝请求期间，服务器最多每 15 分钟记录一次配置错误警告（在收到带有有效 X-Edge-Auth 的请求后重置），因此 secret 不匹配会在日志中可见，而不会为每个被拒绝的请求产生一行日志。

Tools

Core| Tool | Description |

Kafka| Tool | Description |

PostgreSQL| Tool | Description |

Applications

| Tool | Description |
|---|---|
| aiven_application_deploy | 将 Docker 化应用部署到 Aiven |
| aiven_application_redeploy | 重新构建并重新部署现有应用 |
| aiven_vcs_integration_list | 列出已连接的 VCS (GitHub) 账户 |
| aiven_vcs_integration_repository_list | 列出 VCS 集成的仓库 |

Documentation

| Tool | Description |
|---|---|
| aiven_docs_search | 使用自然语言搜索 Aiven 官方文档。仅在托管服务器 (https://mcp.aiven.live/mcp) 上可用 —— 不在自托管部署中提供。 |

Contributing

有关开发环境搭建、本地运行和添加新工具，请参阅 CONTRIBUTING.md。

License

Apache-2.0