MCP StreamableHTTP 客户端

一个桥接客户端，使本地的MCP（模型上下文协议）客户端（如Claude Desktop）能够连接到使用StreamableHTTP传输并需要OAuth认证的远程MCP服务器。

概述

mcp-streamablehttp-client充当协议桥接器，转换以下内容：

• 标准输入输出（stdio） - 由本地MCP客户端使用
• 流式HTTP（StreamableHTTP） - 由带有OAuth保护的远程MCP服务器使用

这使得支持基于stdio的MCP服务器的工具可以无缝集成OAuth保护的MCP服务。

特性

• OAuth 2.0 认证 - 完整支持动态客户端注册（RFC 7591）和管理（RFC 7592）
• 自动令牌管理 - 处理令牌刷新、存储和过期
• 协议桥接 - 在stdio和StreamableHTTP之间进行透明转换
• 会话管理 - 跨协议边界维护MCP会话
• 智能命令解析 - 支持灵活的参数格式，便于工具使用
• Claude Desktop 集成 - 直接配置支持

安装

使用pixi（推荐）

pixi add --pypi mcp-streamablehttp-client

使用pip

pip install m

Docker 部署

FROM python:3.11-slim

# 安装包
RUN pip install mcp-streamablehttp-client

# 设置工作目录
WORKDIR /app

# 复制.env文件（如果存在）
COPY .env* ./

# 运行客户端
CMD ["mcp-streamablehttp-client"]

使用Docker Compose

services:
  mcp-client:
    image: mcp-streamablehttp-client:latest
    build:
      context: ./mcp-streamablehttp-client
    environment:
      - MCP_SERVER_URL=${MCP_SERVER_URL}
    volumes:
      - ./.env:/app/.env:ro
    stdin_open: true
    tty: true

# 使用docker-compose构建和运行
docker-compose up -d

快速开始

1. 初始设置

首先，与您的MCP服务器进行身份验证：

# 使用just（推荐）
just auth

# 或直接
mcp-streamablehttp-client --token

这将引导您完成OAuth流程，并将您的凭据保存到.env中。

2. 测试连接

验证您的身份验证：

just test-auth

3. 与Claude Desktop一起使用

在您的claude_desktop_config.json中添加：

{
  "mcpServers": {
    "my-oauth-server": {
      "command": "mcp-streamablehttp-client",
      "env": {
        "MCP_SERVER_URL": "https://mcp-fetch.yourdomain.com"
      }
    }
  }
}

4. 执行命令

运行MCP工具命令：

# 列出可用工具
just list-tools

# 执行工具
just exec "fetch https://example.com"
just exec "echo message='Hello World'"

配置

所有配置均通过.env中的环境变量完成：

变量	描述	是否必需
MCP_SERVER_URL	目标MCP服务器URL	是
MCP_CLIENT_ID	OAuth客户端ID	自动生成
MCP_CLIENT_SECRET	OAuth客户端密钥	自动生成
MCP_CLIENT_ACCESS_TOKEN	当前访问令牌	自动生成
MCP_CLIENT_REFRESH_TOKEN	刷新令牌	自动生成
MCP_CLIENT_REGISTRATION_TOKEN	RFC 7592管理令牌	自动生成
MCP_CLIENT_REGISTRATION_URI	RFC 7592管理端点	自动生成

使用

命令行命令

身份验证命令

# 设置或刷新OAuth令牌
mcp-streamablehttp-client --token

# 测试身份验证状态
mcp-streamablehttp-client --test-auth

# 清除所有凭据
mcp-streamablehttp-client --reset-auth

MCP命令

# 列出可用工具
mcp-streamablehttp-client --list-tools

# 列出可用资源
mcp-streamablehttp-client --list-resources

# 列出可用提示
mcp-streamablehttp-client --list-prompts

# 执行工具命令
mcp-streamablehttp-client -c "tool_name arguments"

客户端管理（RFC 7592）

# 获取客户端注册信息
mcp-streamablehttp-client --get-client-info

# 更新客户端注册
mcp-streamablehttp-client --update-client "client_name=New Name,contacts=admin@example.com"

# 删除客户端注册
mcp-streamablehttp-client --delete-client

高级用法

# 发送原始JSON-RPC请求
mcp-streamablehttp-client --raw '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'

# 作为持续代理运行（用于Claude Desktop）
mcp-streamablehttp-client

命令参数格式

客户端支持多种参数格式以提高灵活性：

# JSON格式（适用于复杂参数）
mcp-streamablehttp-client -c 'tool {"key": "value", "nested": {"foo": "bar"}}'

# 键值对格式
mcp-streamablehttp-client -c 'tool key1=value1 key2=value2'

# 智能检测（URL、路径等）
mcp-streamablehttp-client -c 'fetch https://example.com'
mcp-streamablehttp-client -c 'read_file /path/to/file.txt'

# 简单字符串参数
mcp-streamablehttp-client -c 'echo "Hello World"'

架构

┌─────────────────────┐     stdio      ┌──────────────────────┐     HTTP + OAuth    ┌─────────────────┐
│   Claude Desktop    │ ←------------→ │ mcp-streamablehttp-  │ ←----------------→ │  Remote MCP     │
│  (或其他stdio       │   JSON-RPC     │      client          │  StreamableHTTP    │    Server       │
│    MCP客户端)       │                │  (协议桥接器)        │                    │ (OAuth保护)     │
└─────────────────────┘                └──────────────────────┘                    └─────────────────┘

客户端充当透明桥接器，处理：

• 协议转换（stdio ↔ HTTP）
• OAuth认证（令牌注入）
• 会话管理（状态保存）
• 错误翻译（HTTP → JSON-RPC）

安全性

• OAuth令牌安全地存储在.env文件中
• 在到期前自动刷新令牌
• 默认启用SSL/TLS验证
• 支持授权码流程中的PKCE
• 客户端凭证不会暴露在日志中

开发

运行测试

# 运行所有测试
just test

# 运行特定测试
just test-auth

构建

# 构建Docker镜像
just build

# 不使用缓存重新构建
just rebuild

故障排除

常见问题

1. “未找到凭据”

   • 运行mcp-streamablehttp-client --token进行身份验证

2. “令牌已过期”

   • 客户端应自动刷新，但您可以使用--token强制刷新

3. “未找到OAuth服务器”

   • 检查MCP_SERVER_URL是否正确
   • 确保服务器支持OAuth发现

4. “权限被拒绝”

   • 您的OAuth用户可能没有访问请求资源的权限
   • 请咨询管理员

调试模式

设置环境变量以启用详细日志记录：

export MCP_DEBUG=1
mcp-streamablehttp-client --test-auth

示例

查看examples/目录：

• claude_desktop_config.json - Claude Desktop配置
• command_examples.sh - 常见命令模式
• demo.py - Python集成示例
• token_example.md - OAuth流程指南

许可

[许可信息在此处]

贡献

[贡献指南在此处]