aws/mcp-proxy-for-aws

# AWS 的 MCP 代理 ## 概述 **MCP Proxy for AWS** 包提供了两种方式将 AI 应用程序连接到 AWS 上的 MCP 服务器： 1. **作为代理使用** — 它成为 MCP 客户端（如 Claude Desktop、Kiro CLI）与 AWS 上 MCP 服务器之间的轻量级客户端侧桥梁。（参见 [MCP 代理](#mcp-proxy)） 2. **作为库使用** — 以编程方式将流行的 AI 代理框架（LangChain、LlamaIndex、Strands Agents 等）连接到 AWS 上的 MCP 服务器。（参见 [程序化访问](#programmatic-access)） ### 何时需要此包？ - 您希望连接到使用 AWS IAM 身份验证（SigV4）而不是 OAuth 的 **AWS 上的 MCP 服务器**（例如使用 Amazon Bedrock AgentCore） - 您使用的 MCP 客户端（如 Claude Desktop、Kiro CLI）不原生支持 AWS IAM 身份验证 - 您正在使用 LangChain、Strands Agents、LlamaIndex 等流行框架构建 AI 代理，需要连接到 AWS 上的 MCP 服务器 - 您希望避免自行构建 SigV4 请求签名逻辑 ### 此包如何提供帮助 **问题：** 官方 MCP 规范支持基于 OAuth 的身份验证，但 AWS 上的 MCP 服务器也可以使用 AWS IAM 身份验证（SigV4）。标准 MCP 客户端不知道如何用 AWS 凭据对请求进行签名。 **解决方案：** 此包通过以下方式弥合这一差距： - **自动处理 SigV4 身份验证** — 使用您的本地 AWS 凭据（来自 AWS CLI、环境变量或 IAM 角色）对所有 MCP 请求进行签名，使用 [SigV4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) - **提供无缝集成** — 与现有 MCP 客户端和框架配合使用 - **消除自定义代码** — 无需构建带有 SigV4 签名逻辑的自己的 MCP 客户端 ## 应该使用哪个功能？ **如果希望使用代理：** - 将 Claude Desktop 或 Kiro CLI 等 MCP 客户端连接到带有 IAM 凭据的 AWS 上的 MCP 服务器 - 将 AWS 上的 MCP 服务器添加到 AI 助手的配置中 - 使用作为代理在 MCP 客户端和 AWS 之间运行的命令行工具 **如果希望作为库使用：** - 使用 LangChain、Strands Agents 或 LlamaIndex 等流行框架以编程方式构建 AI 代理 - 将使用 AWS IAM 保护的 MCP 服务器直接集成到 Python 应用程序中 - 在代码中拥有对 MCP 会话生命周期的细粒度控制 ## 先决条件 * [安装 Python 3.10+](https://www.python.org/downloads/release/python-3100/) * [安装 `uv` 包管理器](https://docs.astral.sh/uv/getting-started/installation/) * 配置 AWS 凭据（通过 [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html)、环境变量或 IAM 角色） * （可选，针对 Docker 用户）[安装 Docker Desktop](https://www.docker.com/products/docker-desktop) ## MCP 代理 MCP 代理作为 MCP 客户端（AI 助理和开发工具）与 AWS 上基于 IAM 的 MCP 服务器之间的轻量级客户端侧桥梁。代理使用本地 AWS 凭据处理 SigV4 身份验证，并提供动态工具发现。 ### 安装 #### 使用 PyPi ``` # 运行服务器 uvx mcp-proxy-for-aws@latest ``` **注意：** 首次运行可能需要数十秒，因为 `uvx` 会下载并缓存依赖项。后续运行将在数秒内启动。实际启动时间取决于您的网络和硬件。 #### 使用本地仓库 ``` git clone https://github.com/aws/mcp-proxy-for-aws.git cd mcp-proxy-for-aws uv run mcp_proxy_for_aws/server.py ``` #### 使用 Docker Docker 镜像已发布到 [公共 AWS ECR 注册表](https://gallery.ecr.aws/mcp-proxy-for-aws/mcp-proxy-for-aws)。 您可以使用预构建的镜像： ``` # 拉取最新镜像 docker pull public.ecr.aws/mcp-proxy-for-aws/mcp-proxy-for-aws:latest # 或者拉取特定版本 docker pull public.ecr.aws/mcp-proxy-for-aws/mcp-proxy-for-aws:1.1.6 ``` 或者本地构建镜像： ``` # 构建 Docker 镜像 docker build -t mcp-proxy-for-aws . ``` ### 配置参数 | 参数 | 描述 | 默认值 | 是否必需 | |------|------|--------|----------| | `endpoint` | MCP 端点 URL（例如 `https://your-service.us-east-1.amazonaws.com/mcp`） | N/A | 是 | | --- | --- | --- | --- | | `--service` | 用于 SigV4 签名的 AWS 服务名称，如果省略则尝试从 URL 推断 | 从端点推断（如果未提供） | 否 | | `--profile` | 用于 AWS 凭据的 AWS 配置文件 | 如果未设置则使用 `AWS_PROFILE` 环境变量 | 否 | | `--region` | 使用的 AWS 区域 | 如果未设置则使用 `AWS_REGION` 环境变量，默认为 `us-east-1` | 否 | | `--metadata` | 以键值对形式注入到 MCP 请求中的元数据（例如 `--metadata KEY1=value1 KEY2=value2`） | 如果未提供，则根据 `--region` 自动注入 `AWS_REGION` | 否 | | `--read-only` | 禁用可能需要写权限的工具（标记为 [`readOnlyHint=true`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint) 的工具不需要写权限） | `False` | 否 | | `--retries` | 配置调用上游服务时的重试次数，设置为 0 可禁用重试 | 0 | 否 | | `--log-level` | 设置日志级别（`DEBUG/INFO/WARNING/ERROR/CRITICAL`） | `INFO` | 否 | | `--timeout` | 为所有操作设置所需的超时秒数 | 180 | 否 | | `--connect-timeout` | 设置所需的连接超时秒数 | 60 | 否 | | `--read-timeout` | 设置所需的读取超时秒数 | 120 | 否 | | `--write-timeout` | 设置所需的写入超时秒数 | 180 | 否 | | `--tool-timeout` | 工具调用在被取消前的最大秒数。超时后，代理会向代理返回错误而不是无限期挂起 | 300 | 否 | | `--disable-telemetry` | 禁用遥测数据收集 | `False` | 否 | ### 可选环境变量 设置 MCP 代理的环境变量： ``` # 通过配置文件获取凭据 export AWS_PROFILE= # 通过参数获取凭据 export AWS_ACCESS_KEY_ID= export AWS_SECRET_ACCESS_KEY= export AWS_SESSION_TOKEN= # AWS 区域 export AWS_REGION= ``` ### 设置示例 将以下配置添加到 MCP 客户端配置文件中（例如，对于 Kiro CLI，请编辑 `~/.kiro/settings/mcp.json`）： **注意** 通过替换 `` 添加您自己的端点 #### 使用 uv 从本地运行 ``` { "mcpServers": { "": { "disabled": false, "type": "stdio", "command": "uv", "args": [ "--directory", "/path/to/mcp_proxy_for_aws", "run", "server.py", "", "--service", "", "--profile", "default", "--region", "us-east-1", "--read-only", "--log-level", "INFO", ] } } } ``` #### 使用 Docker 使用预构建的公共 ECR 镜像： ``` { "mcpServers": { "": { "command": "docker", "args": [ "run", "-i", "--rm", "--volume", "/full/path/to/.aws:/app/.aws:ro", "public.ecr.aws/mcp-proxy-for-aws/mcp-proxy-for-aws:latest", "" ], "env": {} } } } ``` 或者使用本地构建的镜像： ``` { "mcpServers": { "": { "command": "docker", "args": [ "run", "--rm", "--volume", "/full/path/to/.aws:/app/.aws:ro", "mcp-proxy-for-aws", "" ], "env": {} } } } ``` ## 程序化访问 MCP Proxy for AWS 使 IAM-保护的 MCP 服务器能够以编程方式集成到 AI 代理框架中。该库提供与流行 Python AI 框架兼容的身份验证传输层。 默认情况下，该库会自动从标准 [boto3 凭据链](https://docs.aws.amazon.com/boto3/latest/guide/credentials.html#configuring-credentials)（环境变量、共享凭据文件等）解析 AWS 凭据。您可以选择通过 `credentials` 参数以编程方式传递凭据。当提供时，这些参数优先于 `aws_profile` 参数。请注意，使用 `credentials` 时必须显式指定 `aws_region`。注意，当凭据在会话期间过期时，代理会自动检测到身份验证失败并在下一个请求中获取刷新后的凭据 — 无需重新启动。只需刷新凭据（例如运行 `aws sso login`）然后重试。 ### 集成模式 该库支持两种集成模式，具体取决于您的框架： #### 模式 1：客户端工厂集成 **适用于：** 接受返回 MCP 客户端的工厂函数的框架，例如 Strands Agents、Microsoft Agent Framework。`aws_iam_streamablehttp_client` 作为工厂传递给框架，框架内部处理连接生命周期。 **示例 - Strands Agents：** ``` from mcp_proxy_for_aws.client import aws_iam_streamablehttp_client mcp_client_factory = lambda: aws_iam_streamablehttp_client( endpoint=mcp_url, # The URL of the MCP server aws_region=region, # The region of the MCP server aws_service=service # The underlying AWS service, e.g. "bedrock-agentcore" ) with MCPClient(mcp_client_factory) as mcp_client: mcp_tools = mcp_client.list_tools_sync() agent = Agent(tools=mcp_tools, ...) ``` **示例 - Microsoft Agent Framework：** ``` from mcp_proxy_for_aws.client import aws_iam_streamablehttp_client mcp_client_factory = lambda: aws_iam_streamablehttp_client( endpoint=mcp_url, # The URL of the MCP server aws_region=region, # The region of the MCP server aws_service=service # The underlying AWS service, e.g. "bedrock-agentcore" ) mcp_tools = MCPStreamableHTTPTool(name="MCP Tools", url=mcp_url) mcp_tools.get_mcp_client = mcp_client_factory async with mcp_tools: agent = ChatAgent(tools=[mcp_tools], ...) ``` #### 模式 2：直接 MCP 会话集成 **适用于：** 需要直接访问 MCP 会话的框架，例如 LangChain、LlamaIndex。`aws_iam_streamablehttp_client` 提供经过身份验证的传输流，然后用于创建 MCP `ClientSession`。 **示例 - LangChain：** ``` from mcp_proxy_for_aws.client import aws_iam_streamablehttp_client mcp_client = aws_iam_streamablehttp_client( endpoint=mcp_url, # The URL of the MCP server aws_region=region, # The region of the MCP server aws_service=service # The underlying AWS service, e.g. "bedrock-agentcore" ) async with mcp_client as (read, write, session_id_callback): async with ClientSession(read, write) as session: mcp_tools = await load_mcp_tools(session) agent = create_langchain_agent(tools=mcp_tools, ...) ``` **示例 - LlamaIndex：** ``` from mcp_proxy_for_aws.client import aws_iam_streamablehttp_client mcp_client = aws_iam_streamablehttp_client( endpoint=mcp_url, # The URL of the MCP server aws_region=region, # The region of the MCP server aws_service=service # The underlying AWS service, e.g. "bedrock-agentcore" ) async with mcp_client as (read, write, session_id_callback): async with ClientSession(read, write) as session: mcp_tools = await McpToolSpec(client=session).to_tool_list_async() agent = ReActAgent(tools=mcp_tools, ...) ``` ### 运行示例 在 [`./examples/mcp-client`](./examples/mcp-client) 目录中探索适用于不同框架的完整工作示例： **可用示例：** - **[LangChain](./examples/mcp-client/langchain/)** - **[LlamaIndex](./examples/mcp-client/llamaindex/)** - **[Microsoft Agent Framework]( - SigV4 签名器： - SigV4a： ## 许可证 版权所有 Amazon.com, Inc. 或其附属公司。保留所有权利。 根据 Apache License, Version 2.0（“许可证”）授权。 ## 免责声明 大语言模型具有非确定性，它们可能会犯错，我们建议您始终彻底测试并在生产环境中遵循组织的最佳实践。本包的仅供您自行承担风险使用。使用此包的您必须实施适当的安全控制，并且必须使用 AWS 身份和访问管理（IAM）来管理对 AWS 资源的访问。您负责配置适当的 IAM 策略、角色和权限，因 IAM 配置不当导致的安全漏洞由您承担全部责任。通过使用此包，您确认已阅读并理解本免责声明，并同意自行承担使用此包的风险。

标签：AI助理, AI应用集成, AWS, AWS凭证, Bedrock AgentCore, DPI, IAM角色, LangChain, LlamaIndex, MCP, SEO: AI连接AWS, SEO: AWS MCP Proxy, SEO: MCP代理, SigV4认证, Strands Agents, 客户端代理, 无缝集成, 程序化访问, 认证桥接, 请求拦截, 请求签名, 轻量级, 轻量级代理, 逆向工具, 领域:云计算, 领域:人工智能