MCP Streamablehttp Client

MCP流式HTTP客户端

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

概述

这 mcp-streamablehttp-client 充当协议网桥，在以下之间进行转换：

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

这使得OAuth保护的MCP服务能够与仅支持基于stdio的MCP服务器的工具无缝集成。

特性

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

安装

使用pixi（推荐）

pixi add --pypi mcp-streamablehttp-client

使用pip

pip install mcp-streamablehttp-client

Docker部署

FROM python:3.11-slim

# Install the package
RUN pip install mcp-streamablehttp-client

# Set working directory
WORKDIR /app

# Copy .env file (if exists)
COPY .env* ./

# Run the client
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

# Build and run with docker-compose
docker-compose up -d

快速开始

1.初始设置

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

# Using just (recommended)
just auth

# Or directly
mcp-streamablehttp-client --token

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

2.测试连接

验证您的身份验证：

just test-auth

3.与克劳德桌面一起使用

添加到您的 claude_desktop_config.json:

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

4.执行命令

运行MCP工具命令：

# List available tools
just list-tools

# Execute a tool
just exec "fetch https://example.com"
just exec "echo message='Hello World'"

配置

所有配置都是通过环境变量完成的 .env:

用法

CLI命令

身份验证命令

# Setup or refresh OAuth tokens
mcp-streamablehttp-client --token

# Test authentication status
mcp-streamablehttp-client --test-auth

# Clear all credentials
mcp-streamablehttp-client --reset-auth

MCP命令

# List available tools
mcp-streamablehttp-client --list-tools

# List available resources
mcp-streamablehttp-client --list-resources

# List available prompts
mcp-streamablehttp-client --list-prompts

# Execute a tool command
mcp-streamablehttp-client -c "tool_name arguments"

客户端管理（RFC 7592）

# Get client registration info
mcp-streamablehttp-client --get-client-info

# Update client registration
mcp-streamablehttp-client --update-client "client_name=New Name,contacts=admin@example.com"

# Delete client registration
mcp-streamablehttp-client --delete-client

高级用法

# Send raw JSON-RPC request
mcp-streamablehttp-client --raw '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'

# Run as continuous proxy (for Claude Desktop)
mcp-streamablehttp-client

命令参数格式

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

# JSON format (for complex arguments)
mcp-streamablehttp-client -c 'tool {"key": "value", "nested": {"foo": "bar"}}'

# Key=value format
mcp-streamablehttp-client -c 'tool key1=value1 key2=value2'

# Smart detection (URLs, paths, etc.)
mcp-streamablehttp-client -c 'fetch https://example.com'
mcp-streamablehttp-client -c 'read_file /path/to/file.txt'

# Simple string arguments
mcp-streamablehttp-client -c 'echo "Hello World"'

建筑

┌─────────────────────┐     stdio      ┌──────────────────────┐     HTTP + OAuth    ┌─────────────────┐
│   Claude Desktop    │ ←------------→ │ mcp-streamablehttp-  │ ←----------------→ │  Remote MCP     │
│  (or other stdio    │   JSON-RPC     │      client          │  StreamableHTTP    │    Server       │
│    MCP client)      │                │  (Protocol Bridge)   │                    │ (OAuth Protected)│
└─────────────────────┘                └──────────────────────┘                    └─────────────────┘

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

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

安全

• OAuth令牌安全地存储在 .env 文件
• 到期前自动刷新令牌
• 默认情况下启用SSL/TLS验证
• 支持授权码流的PKCE
• 客户端凭据从未在日志中公开

发展

运行测试

# Run all tests
just test

# Run specific test
just test-auth

建筑

# Build Docker image
just build

# Rebuild with no cache
just rebuild

故障排除

常见问题

1. “找不到凭据”

- 跑 mcp-streamablehttp-client --token 鉴定

1. “令牌已过期”

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

1. “找不到OAuth服务器”

- 检查 MCP_SERVER_URL 是正确的 - 确保服务器支持OAuth发现

1. “权限被拒绝”

- 您的OAuth用户可能无法访问所请求的资源 - 请与管理员联系

调试模式

设置详细日志记录的环境变量：

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

例子

请参阅 examples/ 目录：

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

许可证

\[此处为许可证信息\]

贡献

\[此处为投稿指南\]