[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-geelen--mcp-remote":3,"tool-geelen--mcp-remote":64},[4,16,31,40,48,56],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":15},4721,"markitdown","microsoft\u002Fmarkitdown","MarkItDown 是一款由微软 AutoGen 团队打造的轻量级 Python 工具，专为将各类文件高效转换为 Markdown 格式而设计。它支持 PDF、Word、Excel、PPT、图片（含 OCR）、音频（含语音转录）、HTML 乃至 YouTube 链接等多种格式的解析，能够精准提取文档中的标题、列表、表格和链接等关键结构信息。\n\n在人工智能应用日益普及的今天，大语言模型（LLM）虽擅长处理文本，却难以直接读取复杂的二进制办公文档。MarkItDown 恰好解决了这一痛点，它将非结构化或半结构化的文件转化为模型“原生理解”且 Token 效率极高的 Markdown 格式，成为连接本地文件与 AI 分析 pipeline 的理想桥梁。此外，它还提供了 MCP（模型上下文协议）服务器，可无缝集成到 Claude Desktop 等 LLM 应用中。\n\n这款工具特别适合开发者、数据科学家及 AI 研究人员使用，尤其是那些需要构建文档检索增强生成（RAG）系统、进行批量文本分析或希望让 AI 助手直接“阅读”本地文件的用户。虽然生成的内容也具备一定可读性，但其核心优势在于为机器",93400,2,"2026-04-06T19:52:38",[13,14],"插件","开发框架","ready",{"id":17,"name":18,"github_repo":19,"description_zh":20,"stars":21,"difficulty_score":10,"last_commit_at":22,"category_tags":23,"status":15},2268,"ML-For-Beginners","microsoft\u002FML-For-Beginners","ML-For-Beginners 是由微软推出的一套系统化机器学习入门课程，旨在帮助零基础用户轻松掌握经典机器学习知识。这套课程将学习路径规划为 12 周，包含 26 节精炼课程和 52 道配套测验，内容涵盖从基础概念到实际应用的完整流程，有效解决了初学者面对庞大知识体系时无从下手、缺乏结构化指导的痛点。\n\n无论是希望转型的开发者、需要补充算法背景的研究人员，还是对人工智能充满好奇的普通爱好者，都能从中受益。课程不仅提供了清晰的理论讲解，还强调动手实践，让用户在循序渐进中建立扎实的技能基础。其独特的亮点在于强大的多语言支持，通过自动化机制提供了包括简体中文在内的 50 多种语言版本，极大地降低了全球不同背景用户的学习门槛。此外，项目采用开源协作模式，社区活跃且内容持续更新，确保学习者能获取前沿且准确的技术资讯。如果你正寻找一条清晰、友好且专业的机器学习入门之路，ML-For-Beginners 将是理想的起点。",85013,"2026-04-06T11:09:19",[24,25,26,13,27,28,29,14,30],"图像","数据工具","视频","Agent","其他","语言模型","音频",{"id":32,"name":33,"github_repo":34,"description_zh":35,"stars":36,"difficulty_score":37,"last_commit_at":38,"category_tags":39,"status":15},2181,"OpenHands","OpenHands\u002FOpenHands","OpenHands 是一个专注于 AI 驱动开发的开源平台，旨在让智能体（Agent）像人类开发者一样理解、编写和调试代码。它解决了传统编程中重复性劳动多、环境配置复杂以及人机协作效率低等痛点，通过自动化流程显著提升开发速度。\n\n无论是希望提升编码效率的软件工程师、探索智能体技术的研究人员，还是需要快速原型验证的技术团队，都能从中受益。OpenHands 提供了灵活多样的使用方式：既可以通过命令行（CLI）或本地图形界面在个人电脑上轻松上手，体验类似 Devin 的流畅交互；也能利用其强大的 Python SDK 自定义智能体逻辑，甚至在云端大规模部署上千个智能体并行工作。\n\n其核心技术亮点在于模块化的软件智能体 SDK，这不仅构成了平台的引擎，还支持高度可组合的开发模式。此外，OpenHands 在 SWE-bench 基准测试中取得了 77.6% 的优异成绩，证明了其解决真实世界软件工程问题的能力。平台还具备完善的企业级功能，支持与 Slack、Jira 等工具集成，并提供细粒度的权限管理，适合从个人开发者到大型企业的各类用户场景。",70771,3,"2026-04-07T23:08:25",[29,27,14,13],{"id":41,"name":42,"github_repo":43,"description_zh":44,"stars":45,"difficulty_score":10,"last_commit_at":46,"category_tags":47,"status":15},51,"gstack","garrytan\u002Fgstack","gstack 是 Y Combinator CEO Garry Tan 亲自开源的一套 AI 工程化配置，旨在将 Claude Code 升级为你的虚拟工程团队。面对单人开发难以兼顾产品战略、架构设计、代码审查及质量测试的挑战，gstack 提供了一套标准化解决方案，帮助开发者实现堪比二十人团队的高效产出。\n\n这套配置特别适合希望提升交付效率的创始人、技术负责人，以及初次尝试 Claude Code 的开发者。gstack 的核心亮点在于内置了 15 个具有明确职责的 AI 角色工具，涵盖 CEO、设计师、工程经理、QA 等职能。用户只需通过简单的斜杠命令（如 `\u002Freview` 进行代码审查、`\u002Fqa` 执行测试、`\u002Fplan-ceo-review` 规划功能），即可自动化处理从需求分析到部署上线的全链路任务。\n\n所有操作基于 Markdown 和斜杠命令，无需复杂配置，完全免费且遵循 MIT 协议。gstack 不仅是一套工具集，更是一种现代化的软件工厂实践，让单人开发者也能拥有严谨的工程流程。",66449,"2026-04-07T23:09:28",[27,13],{"id":49,"name":50,"github_repo":51,"description_zh":52,"stars":53,"difficulty_score":10,"last_commit_at":54,"category_tags":55,"status":15},3074,"gpt4free","xtekky\u002Fgpt4free","gpt4free 是一个由社区驱动的开源项目，旨在聚合多种可访问的大型语言模型（LLM）和媒体生成接口，让用户能更灵活、便捷地使用前沿 AI 能力。它解决了直接调用各类模型时面临的接口分散、门槛高或成本昂贵等痛点，通过统一的标准将不同提供商的资源整合在一起。\n\n无论是希望快速集成 AI 功能的开发者、需要多模型对比测试的研究人员，还是想免费体验最新技术的普通用户，都能从中受益。gpt4free 提供了丰富的使用方式：既包含易于上手的 Python 和 JavaScript 客户端库，也支持部署本地图形界面（GUI），更提供了兼容 OpenAI 标准的 REST API，方便无缝替换现有应用后端。\n\n其技术亮点在于强大的多提供商支持架构，能够动态调度包括 Opus、Gemini、DeepSeek 等多种主流模型资源，并支持 Docker 一键部署及本地推理。项目秉持社区优先原则，在降低使用门槛的同时，也为贡献者提供了扩展新接口的便利框架，是探索和利用多样化 AI 资源的实用工具。",65970,"2026-04-04T01:02:03",[13,29,27],{"id":57,"name":58,"github_repo":59,"description_zh":60,"stars":61,"difficulty_score":10,"last_commit_at":62,"category_tags":63,"status":15},193,"meilisearch","meilisearch\u002Fmeilisearch","Meilisearch 是一个开源的极速搜索服务，专为现代应用和网站打造，开箱即用。它能帮助开发者快速集成高质量的搜索功能，无需复杂的配置或额外的数据预处理。传统搜索方案往往需要大量调优才能实现准确结果，而 Meilisearch 内置了拼写容错、同义词识别、即时响应等实用特性，并支持 AI 驱动的混合搜索（结合关键词与语义理解），显著提升用户查找信息的体验。\n\nMeilisearch 特别适合 Web 开发者、产品团队或初创公司使用，尤其适用于需要快速上线搜索功能的场景，如电商网站、内容平台或 SaaS 应用。它提供简洁的 RESTful API 和多种语言 SDK，部署简单，资源占用低，本地开发或生产环境均可轻松运行。对于希望在不依赖大型云服务的前提下，为用户提供流畅、智能搜索体验的团队来说，Meilisearch 是一个高效且友好的选择。",57002,"2026-04-07T20:53:30",[24,27,25,14,13,28],{"id":65,"github_repo":66,"name":67,"description_en":68,"description_zh":69,"ai_summary_zh":70,"readme_en":71,"readme_zh":72,"quickstart_zh":73,"use_case_zh":74,"hero_image_url":75,"owner_login":76,"owner_name":77,"owner_avatar_url":78,"owner_bio":68,"owner_company":68,"owner_location":79,"owner_email":80,"owner_twitter":68,"owner_website":81,"owner_url":82,"languages":83,"stars":92,"forks":93,"last_commit_at":94,"license":95,"difficulty_score":10,"env_os":96,"env_gpu":97,"env_ram":97,"env_deps":98,"category_tags":103,"github_topics":68,"view_count":10,"oss_zip_url":68,"oss_zip_packed_at":68,"status":15,"created_at":104,"updated_at":105,"faqs":106,"releases":136},5424,"geelen\u002Fmcp-remote","mcp-remote",null,"mcp-remote 是一款旨在打通本地与远程连接的桥梁工具，专门用于让仅支持本地（stdio）通信的 MCP 客户端也能安全访问远程 MCP 服务器。目前，许多流行的 AI 开发工具（如 Claude Desktop、Cursor）出于安全和便捷考虑，默认只运行本地服务，这虽然保护了隐私，却阻碍了开发者享受云端部署带来的快速迭代和集中维护优势。\n\nmcp-remote 巧妙地解决了这一矛盾：它在本地充当代理，将客户端的本地请求转发至远程服务器，并完整支持最新的 MCP 授权规范（包括 OAuth 流程）。这意味着开发者无需等待客户端原生支持远程连接，即可立即使用托管在云端的强大服务，同时确保 API 密钥等敏感信息不泄露。\n\n该工具特别适合正在构建或试用 MCP 生态的开发者和技术研究人员。其技术亮点在于灵活的配置能力，不仅支持通过命令行参数注入自定义请求头以绕过特定认证限制，还能利用 `--resource` 标志隔离不同租户的 OAuth 会话，轻松实现多实例并行管理。作为一个实验性的概念验证项目，mcp-remote 为当前过渡期的 MCP 生态提供了极具价值的临时解决方案，让","mcp-remote 是一款旨在打通本地与远程连接的桥梁工具，专门用于让仅支持本地（stdio）通信的 MCP 客户端也能安全访问远程 MCP 服务器。目前，许多流行的 AI 开发工具（如 Claude Desktop、Cursor）出于安全和便捷考虑，默认只运行本地服务，这虽然保护了隐私，却阻碍了开发者享受云端部署带来的快速迭代和集中维护优势。\n\nmcp-remote 巧妙地解决了这一矛盾：它在本地充当代理，将客户端的本地请求转发至远程服务器，并完整支持最新的 MCP 授权规范（包括 OAuth 流程）。这意味着开发者无需等待客户端原生支持远程连接，即可立即使用托管在云端的强大服务，同时确保 API 密钥等敏感信息不泄露。\n\n该工具特别适合正在构建或试用 MCP 生态的开发者和技术研究人员。其技术亮点在于灵活的配置能力，不仅支持通过命令行参数注入自定义请求头以绕过特定认证限制，还能利用 `--resource` 标志隔离不同租户的 OAuth 会话，轻松实现多实例并行管理。作为一个实验性的概念验证项目，mcp-remote 为当前过渡期的 MCP 生态提供了极具价值的临时解决方案，让用户能提前体验分布式架构的便利。","# `mcp-remote`\n\nConnect an MCP Client that only supports local (stdio) servers to a Remote MCP Server, with auth support:\n\n**Note: this is a working proof-of-concept** but should be considered **experimental**.\n\n## Why is this necessary?\n\nSo far, the majority of MCP servers in the wild are installed locally, using the stdio transport. This has some benefits: both the client and the server can implicitly trust each other as the user has granted them both permission to run. Adding secrets like API keys can be done using environment variables and never leave your machine. And building on `npx` and `uvx` has allowed users to avoid explicit install steps, too.\n\nBut there's a reason most software that _could_ be moved to the web _did_ get moved to the web: it's so much easier to find and fix bugs & iterate on new features when you can push updates to all your users with a single deploy.\n\nWith the latest MCP [Authorization specification](https:\u002F\u002Fmodelcontextprotocol.io\u002Fspecification\u002F2025-03-26\u002Fbasic\u002Fauthorization), we now have a secure way of sharing our MCP servers with the world _without_ running code on user's laptops. Or at least, you would, if all the popular MCP _clients_ supported it yet. Most are stdio-only, and those that _do_ support HTTP+SSE don't yet support the OAuth flows required.\n\nThat's where `mcp-remote` comes in. As soon as your chosen MCP client supports remote, authorized servers, you can remove it. Until that time, drop in this one liner and dress for the MCP clients you want!\n\n## Usage\n\nAll the most popular MCP clients (Claude Desktop, Cursor & Windsurf) use the following config format:\n\n```json\n{\n  \"mcpServers\": {\n    \"remote-example\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"mcp-remote\",\n        \"https:\u002F\u002Fremote.mcp.server\u002Fsse\"\n      ]\n    }\n  }\n}\n```\n\n### Custom Headers\n\nTo bypass authentication, or to emit custom headers on all requests to your remote server, pass `--header` CLI arguments:\n\n```json\n{\n  \"mcpServers\": {\n    \"remote-example\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"mcp-remote\",\n        \"https:\u002F\u002Fremote.mcp.server\u002Fsse\",\n        \"--header\",\n        \"Authorization: Bearer ${AUTH_TOKEN}\"\n      ],\n      \"env\": {\n        \"AUTH_TOKEN\": \"...\"\n      }\n    },\n  }\n}\n```\n\n**Note:** Cursor and Claude Desktop (Windows) have a bug where spaces inside `args` aren't escaped when it invokes `npx`, which ends up mangling these values. You can work around it using:\n\n```jsonc\n{\n  \u002F\u002F rest of config...\n  \"args\": [\n    \"mcp-remote\",\n    \"https:\u002F\u002Fremote.mcp.server\u002Fsse\",\n    \"--header\",\n    \"Authorization:${AUTH_HEADER}\" \u002F\u002F note no spaces around ':'\n  ],\n  \"env\": {\n    \"AUTH_HEADER\": \"Bearer \u003Cauth-token>\" \u002F\u002F spaces OK in env vars\n  }\n},\n```\n\n### Multiple Instances\n\nTo run multiple instances of the same remote server with different configurations (e.g., different Atlassian tenants), use the `--resource` flag to isolate OAuth sessions:\n\n```json\n{\n  \"mcpServers\": {\n    \"atlassian_tenant1\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"mcp-remote\",\n        \"https:\u002F\u002Fmcp.atlassian.com\u002Fv1\u002Fsse\",\n        \"--resource\",\n        \"https:\u002F\u002Ftenant1.atlassian.net\u002F\"\n      ]\n    },\n    \"atlassian_tenant2\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"mcp-remote\",\n        \"https:\u002F\u002Fmcp.atlassian.com\u002Fv1\u002Fsse\",\n        \"--resource\",\n        \"https:\u002F\u002Ftenant2.atlassian.net\u002F\"\n      ]\n    }\n  }\n}\n```\n\nEach unique combination of server URL, resource, and custom headers will maintain separate OAuth sessions and token storage.\n\n### Flags\n\n* If `npx` is producing errors, consider adding `-y` as the first argument to auto-accept the installation of the `mcp-remote` package.\n\n```json\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"mcp-remote\",\n        \"https:\u002F\u002Fremote.mcp.server\u002Fsse\"\n      ]\n```\n\n* To force `npx` to always check for an updated version of `mcp-remote`, add the `@latest` flag:\n\n```json\n      \"args\": [\n        \"mcp-remote@latest\",\n        \"https:\u002F\u002Fremote.mcp.server\u002Fsse\"\n      ]\n```\n\n* To change which port `mcp-remote` listens for an OAuth redirect (by default `3334`), add an additional argument after the server URL. Note that whatever port you specify, if it is unavailable an open port will be chosen at random.\n\n```json\n      \"args\": [\n        \"mcp-remote\",\n        \"https:\u002F\u002Fremote.mcp.server\u002Fsse\",\n        \"9696\"\n      ]\n```\n\n* To change which host `mcp-remote` registers as the OAuth callback URL (by default `localhost`), add the `--host` flag.\n\n```json\n      \"args\": [\n        \"mcp-remote\",\n        \"https:\u002F\u002Fremote.mcp.server\u002Fsse\",\n        \"--host\",\n        \"127.0.0.1\"\n      ]\n```\n\n* To allow HTTP connections in trusted private networks, add the `--allow-http` flag. Note: This should only be used in secure private networks where traffic cannot be intercepted.\n\n```json\n      \"args\": [\n        \"mcp-remote\",\n        \"http:\u002F\u002Finternal-service.vpc\u002Fsse\",\n        \"--allow-http\"\n      ]\n```\n\n* To enable detailed debugging logs, add the `--debug` flag. This will write verbose logs to `~\u002F.mcp-auth\u002F{server_hash}_debug.log` with timestamps and detailed information about the auth process, connections, and token refreshing.\n\n```json\n      \"args\": [\n        \"mcp-remote\",\n        \"https:\u002F\u002Fremote.mcp.server\u002Fsse\",\n        \"--debug\"\n      ]\n```\n\n* To suppress default logs, add the `--silent` flag. This will prevent logs from being emitted, except in the case where `--debug` is also passed.\n\n```json\n      \"args\": [\n        \"mcp-remote\",\n        \"https:\u002F\u002Fremote.mcp.server\u002Fsse\",\n        \"--silent\"\n      ]\n```\n\n* To enable an outbound HTTP(S) proxy for mcp-remote, add the `--enable-proxy` flag. When enabled, mcp-remote will use the proxy settings from common environment variables (for example `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY`).\n\n```json\n    \"args\": [\n      \"mcp-remote\",\n      \"https:\u002F\u002Fremote.mcp.server\u002Fsse\",\n      \"--enable-proxy\"\n    ],\n    \"env\": {\n      \"HTTPS_PROXY\": \"http:\u002F\u002F127.0.0.1:3128\",\n      \"NO_PROXY\": \"localhost,127.0.0.1\"\n    }\n```\n\n* To ignore specific tools from the remote server, add the `--ignore-tool` flag. This will filter out tools matching the specified patterns from both `tools\u002Flist` responses and block `tools\u002Fcall` requests. Supports wildcard patterns with `*`.\n\n```json\n      \"args\": [\n        \"mcp-remote\",\n        \"https:\u002F\u002Fremote.mcp.server\u002Fsse\",\n        \"--ignore-tool\",\n        \"delete*\",\n        \"--ignore-tool\",\n        \"remove*\"\n      ]\n```\n\nYou can specify multiple `--ignore-tool` flags to ignore different patterns. Examples:\n- `delete*` - ignores all tools starting with \"delete\" (e.g., `deleteTask`, `deleteUser`)\n- `*account` - ignores all tools ending with \"account\" (e.g., `getAccount`, `updateAccount`)\n- `exactTool` - ignores only the tool named exactly \"exactTool\"\n\n* To change the timeout for the OAuth callback (by default `30` seconds), add the `--auth-timeout` flag with a value in seconds. This is useful if the authentication process on the server side takes a long time.\n\n```json\n      \"args\": [\n        \"mcp-remote\",\n        \"https:\u002F\u002Fremote.mcp.server\u002Fsse\",\n        \"--auth-timeout\",\n        \"60\"\n      ]\n```\n\n### Transport Strategies\n\nMCP Remote supports different transport strategies when connecting to an MCP server. This allows you to control whether it uses Server-Sent Events (SSE) or HTTP transport, and in what order it tries them.\n\nSpecify the transport strategy with the `--transport` flag:\n\n```bash\nnpx mcp-remote https:\u002F\u002Fexample.remote\u002Fserver --transport sse-only\n```\n\n**Available Strategies:**\n\n- `http-first` (default): Tries HTTP transport first, falls back to SSE if HTTP fails with a 404 error\n- `sse-first`: Tries SSE transport first, falls back to HTTP if SSE fails with a 405 error\n- `http-only`: Only uses HTTP transport, fails if the server doesn't support it\n- `sse-only`: Only uses SSE transport, fails if the server doesn't support it\n\n### Static OAuth Client Metadata\n\nMCP Remote supports providing static OAuth client metadata instead of using the mcp-remote defaults.\nThis is useful when connecting to OAuth servers that expect specific client\u002Fsoftware IDs or scopes.\n\nProvide the client metadata as a JSON string or as a `@` prefixed filepath with the `--static-oauth-client-metadata` flag:\n\n```bash\nnpx mcp-remote https:\u002F\u002Fexample.remote\u002Fserver --static-oauth-client-metadata '{ \"scope\": \"space separated scopes\" }'\n# uses node readfile, so you probably want to use absolute paths if you're not sure what the cwd is\nnpx mcp-remote https:\u002F\u002Fexample.remote\u002Fserver --static-oauth-client-metadata '@\u002FUsers\u002Fusername\u002FLibrary\u002FApplication Support\u002FClaude\u002Foauth_client_metadata.json'\n```\n\n### Static OAuth Client Information\n\nPer the [spec](https:\u002F\u002Fmodelcontextprotocol.io\u002Fspecification\u002F2025-03-26\u002Fbasic\u002Fauthorization#2-4-dynamic-client-registration),\nservers are encouraged but not required to support [OAuth dynamic client registration](https:\u002F\u002Fdatatracker.ietf.org\u002Fdoc\u002Fhtml\u002Frfc7591).\n\nFor these servers, MCP Remote supports providing static OAuth client information instead.\nThis is useful when connecting to OAuth servers that require pre-registered clients.\n\nProvide the client metadata as a JSON string or as a `@` prefixed filepath with the `--static-oauth-client-info` flag:\n\n```bash\nexport MCP_REMOTE_CLIENT_ID=xxx\nexport MCP_REMOTE_CLIENT_SECRET=yyy\nnpx mcp-remote https:\u002F\u002Fexample.remote\u002Fserver --static-oauth-client-info \"{ \\\"client_id\\\": \\\"$MCP_REMOTE_CLIENT_ID\\\", \\\"client_secret\\\": \\\"$MCP_REMOTE_CLIENT_SECRET\\\" }\"\n# uses node readfile, so you probably want to use absolute paths if you're not sure what the cwd is\nnpx mcp-remote https:\u002F\u002Fexample.remote\u002Fserver --static-oauth-client-info '@\u002FUsers\u002Fusername\u002FLibrary\u002FApplication Support\u002FClaude\u002Foauth_client_info.json'\n```\n\n### Claude Desktop\n\n[Official Docs](https:\u002F\u002Fmodelcontextprotocol.io\u002Fquickstart\u002Fuser)\n\nIn order to add an MCP server to Claude Desktop you need to edit the configuration file located at:\n\n* macOS: `~\u002FLibrary\u002FApplication Support\u002FClaude\u002Fclaude_desktop_config.json`\n* Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\nIf it does not exist yet, [you may need to enable it under Settings > Developer](https:\u002F\u002Fmodelcontextprotocol.io\u002Fquickstart\u002Fuser#2-add-the-filesystem-mcp-server).\n\nRestart Claude Desktop to pick up the changes in the configuration file.\nUpon restarting, you should see a hammer icon in the bottom right corner\nof the input box.\n\n### Cursor\n\n[Official Docs](https:\u002F\u002Fdocs.cursor.com\u002Fcontext\u002Fmodel-context-protocol). The configuration file is located at `~\u002F.cursor\u002Fmcp.json`.\n\nAs of version `0.48.0`, Cursor supports unauthed SSE servers directly. If your MCP server is using the official MCP OAuth authorization protocol, you still need to add a **\"command\"** server and call `mcp-remote`.\n\n### Windsurf\n\n[Official Docs](https:\u002F\u002Fdocs.codeium.com\u002Fwindsurf\u002Fmcp). The configuration file is located at `~\u002F.codeium\u002Fwindsurf\u002Fmcp_config.json`.\n\n## Building Remote MCP Servers\n\nFor instructions on building & deploying remote MCP servers, including acting as a valid OAuth client, see the following resources:\n\n* https:\u002F\u002Fdevelopers.cloudflare.com\u002Fagents\u002Fguides\u002Fremote-mcp-server\u002F\n\nIn particular, see:\n\n* https:\u002F\u002Fgithub.com\u002Fcloudflare\u002Fworkers-oauth-provider for defining an MCP-comlpiant OAuth server in Cloudflare Workers\n* https:\u002F\u002Fgithub.com\u002Fcloudflare\u002Fagents\u002Ftree\u002Fmain\u002Fexamples\u002Fmcp for defining an `McpAgent` using the [`agents`](https:\u002F\u002Fnpmjs.com\u002Fpackage\u002Fagents) framework.\n\nFor more information about testing these servers, see also:\n\n* https:\u002F\u002Fdevelopers.cloudflare.com\u002Fagents\u002Fguides\u002Ftest-remote-mcp-server\u002F\n\nKnow of more resources you'd like to share? Please add them to this Readme and send a PR!\n\n## Troubleshooting\n\n### Clear your `~\u002F.mcp-auth` directory\n\n`mcp-remote` stores all the credential information inside `~\u002F.mcp-auth` (or wherever your `MCP_REMOTE_CONFIG_DIR` points to). If you're having persistent issues, try running:\n\n```sh\nrm -rf ~\u002F.mcp-auth\n```\n\nThen restarting your MCP client.\n\n### Check your Node version\n\nMake sure that the version of Node you have installed is [18 or\nhigher](https:\u002F\u002Fmodelcontextprotocol.io\u002Fquickstart\u002Fserver). Claude\nDesktop will use your system version of Node, even if you have a newer\nversion installed elsewhere.\n\n### Restart Claude\n\nWhen modifying `claude_desktop_config.json` it can helpful to completely restart Claude\n\n### VPN Certs\n\nYou may run into issues if you are behind a VPN, you can try setting the `NODE_EXTRA_CA_CERTS`\nenvironment variable to point to the CA certificate file. If using `claude_desktop_config.json`,\nthis might look like:\n\n```json\n{\n \"mcpServers\": {\n    \"remote-example\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"mcp-remote\",\n        \"https:\u002F\u002Fremote.mcp.server\u002Fsse\"\n      ],\n      \"env\": {\n        \"NODE_EXTRA_CA_CERTS\": \"{your CA certificate file path}.pem\"\n      }\n    }\n  }\n}\n```\n\n### Check the logs\n\n* [Follow Claude Desktop logs in real-time](https:\u002F\u002Fmodelcontextprotocol.io\u002Fdocs\u002Ftools\u002Fdebugging#debugging-in-claude-desktop)\n* MacOS \u002F Linux:\u003Cbr\u002F>`tail -n 20 -F ~\u002FLibrary\u002FLogs\u002FClaude\u002Fmcp*.log`\n* For bash on WSL:\u003Cbr\u002F>`tail -n 20 -f \"C:\\Users\\YourUsername\\AppData\\Local\\Claude\\Logs\\mcp.log\"`\n* Powershell: \u003Cbr\u002F>`Get-Content \"C:\\Users\\YourUsername\\AppData\\Local\\Claude\\Logs\\mcp.log\" -Wait -Tail 20`\n\n## Debugging\n\n### Debug Logs\n\nFor troubleshooting complex issues, especially with token refreshing or authentication problems, use the `--debug` flag:\n\n```json\n\"args\": [\n  \"mcp-remote\",\n  \"https:\u002F\u002Fremote.mcp.server\u002Fsse\",\n  \"--debug\"\n]\n```\n\nThis creates detailed logs in `~\u002F.mcp-auth\u002F{server_hash}_debug.log` with timestamps and complete information about every step of the connection and authentication process. When you find issues with token refreshing, laptop sleep\u002Fresume issues, or auth problems, provide these logs when seeking support.\n\n### Authentication Errors\n\nIf you encounter the following error, returned by the `\u002Fcallback` URL:\n\n```\nAuthentication Error\nToken exchange failed: HTTP 400\n```\n\nYou can run `rm -rf ~\u002F.mcp-auth` to clear any locally stored state and tokens.\n\n### \"Client\" mode\n\nRun the following on the command line (not from an MCP server):\n\n```shell\nnpx -p mcp-remote@latest mcp-remote-client https:\u002F\u002Fremote.mcp.server\u002Fsse\n```\n\nThis will run through the entire authorization flow and attempt to list the tools & resources at the remote URL. Try this after running `rm -rf ~\u002F.mcp-auth` to see if stale credentials are your problem, otherwise hopefully the issue will be more obvious in these logs than those in your MCP client.\n","# `mcp-remote`\n\n将仅支持本地（stdio）服务器的 MCP 客户端连接到具有身份验证支持的远程 MCP 服务器：\n\n**注意：这只是一个可行的概念验证**，但应被视为 **实验性功能**。\n\n## 为什么需要这个工具？\n\n迄今为止，市面上大多数 MCP 服务器都部署在本地，使用 stdio 传输方式。这种方式有一些优势：由于用户已授予客户端和服务器运行权限，两者可以彼此隐式信任。诸如 API 密钥之类的敏感信息可以通过环境变量进行配置，且始终不会离开用户的机器。此外，借助 `npx` 和 `uvx`，用户无需执行显式的安装步骤即可快速上手。\n\n然而，许多原本可以迁移到云端的软件最终确实被迁移到了云端，原因在于：当你可以通过一次部署就为所有用户推送更新时，查找和修复 bug、迭代新功能会变得容易得多。\n\n借助最新的 MCP [授权规范](https:\u002F\u002Fmodelcontextprotocol.io\u002Fspecification\u002F2025-03-26\u002Fbasic\u002Fauthorization)，我们现在拥有了一种安全的方式，可以在不将代码运行在用户笔记本电脑上的情况下，与全世界共享我们的 MCP 服务器。当然，前提是目前流行的 MCP _客户端_ 都已支持这一功能。然而，大多数客户端仍然只支持 stdio 方式，而那些支持 HTTP+SSE 的客户端也尚未实现所需的 OAuth 流程。\n\n这就引出了 `mcp-remote` 的用武之地。一旦你选择的 MCP 客户端支持远程授权服务器，就可以将其移除。在此之前，只需添加这一行配置，即可适配你所需的 MCP 客户端！\n\n## 使用方法\n\n目前最流行的几款 MCP 客户端（Claude Desktop、Cursor 和 Windsurf）均采用以下配置格式：\n\n```json\n{\n  \"mcpServers\": {\n    \"remote-example\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"mcp-remote\",\n        \"https:\u002F\u002Fremote.mcp.server\u002Fsse\"\n      ]\n    }\n  }\n}\n```\n\n### 自定义请求头\n\n若需绕过身份验证，或在向远程服务器发送的所有请求中附加自定义请求头，可传递 `--header` CLI 参数：\n\n```json\n{\n  \"mcpServers\": {\n    \"remote-example\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"mcp-remote\",\n        \"https:\u002F\u002Fremote.mcp.server\u002Fsse\",\n        \"--header\",\n        \"Authorization: Bearer ${AUTH_TOKEN}\"\n      ],\n      \"env\": {\n        \"AUTH_TOKEN\": \"...\"\n      }\n    },\n  }\n}\n```\n\n**注意：** Cursor 和 Claude Desktop（Windows）存在一个 bug，即在调用 `npx` 时，`args` 中的空格不会被转义，从而导致这些值被错误解析。对此，可以采用如下 workaround：\n\n```jsonc\n{\n  \u002F\u002F 其余配置...\n  \"args\": [\n    \"mcp-remote\",\n    \"https:\u002F\u002Fremote.mcp.server\u002Fsse\",\n    \"--header\",\n    \"Authorization:${AUTH_HEADER}\" \u002F\u002F 注意冒号前后无空格\n  ],\n  \"env\": {\n    \"AUTH_HEADER\": \"Bearer \u003Cauth-token>\" \u002F\u002F 环境变量中的空格是允许的\n  }\n},\n```\n\n### 多实例运行\n\n若需以不同配置（例如针对不同的 Atlassian 租户）同时运行同一远程服务器的多个实例，可使用 `--resource` 标志来隔离 OAuth 会话：\n\n```json\n{\n  \"mcpServers\": {\n    \"atlassian_tenant1\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"mcp-remote\",\n        \"https:\u002F\u002Fmcp.atlassian.com\u002Fv1\u002Fsse\",\n        \"--resource\",\n        \"https:\u002F\u002Ftenant1.atlassian.net\u002F\"\n      ]\n    },\n    \"atlassian_tenant2\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"mcp-remote\",\n        \"https:\u002F\u002Fmcp.atlassian.com\u002Fv1\u002Fsse\",\n        \"--resource\",\n        \"https:\u002F\u002Ftenant2.atlassian.net\u002F\"\n      ]\n    }\n  }\n}\n```\n\n对于每组唯一的服务器 URL、资源标识符和自定义请求头组合，都会维护独立的 OAuth 会话及令牌存储。\n\n### 标志\n\n* 如果 `npx` 产生错误，可以考虑在命令中添加 `-y` 作为第一个参数，以自动接受安装 `mcp-remote` 包。\n\n```json\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"mcp-remote\",\n        \"https:\u002F\u002Fremote.mcp.server\u002Fsse\"\n      ]\n```\n\n* 若要强制 `npx` 始终检查 `mcp-remote` 的更新版本，可添加 `@latest` 标志：\n\n```json\n      \"args\": [\n        \"mcp-remote@latest\",\n        \"https:\u002F\u002Fremote.mcp.server\u002Fsse\"\n      ]\n```\n\n* 若要更改 `mcp-remote` 监听 OAuth 重定向的端口（默认为 `3334`），可在服务器 URL 后添加一个额外的参数。请注意，无论您指定哪个端口，如果该端口不可用，系统将随机选择一个可用端口。\n\n```json\n      \"args\": [\n        \"mcp-remote\",\n        \"https:\u002F\u002Fremote.mcp.server\u002Fsse\",\n        \"9696\"\n      ]\n```\n\n* 若要更改 `mcp-remote` 注册为 OAuth 回调 URL 的主机（默认为 `localhost`），可添加 `--host` 标志。\n\n```json\n      \"args\": [\n        \"mcp-remote\",\n        \"https:\u002F\u002Fremote.mcp.server\u002Fsse\",\n        \"--host\",\n        \"127.0.0.1\"\n      ]\n```\n\n* 若要允许在受信任的私有网络中使用 HTTP 连接，可添加 `--allow-http` 标志。注意：此选项仅应在安全的私有网络中使用，确保流量不会被拦截。\n\n```json\n      \"args\": [\n        \"mcp-remote\",\n        \"http:\u002F\u002Finternal-service.vpc\u002Fsse\",\n        \"--allow-http\"\n      ]\n```\n\n* 若要启用详细的调试日志，可添加 `--debug` 标志。这将在 `~\u002F.mcp-auth\u002F{server_hash}_debug.log` 中写入带有时间戳和关于认证过程、连接及令牌刷新等详细信息的日志。\n\n```json\n      \"args\": [\n        \"mcp-remote\",\n        \"https:\u002F\u002Fremote.mcp.server\u002Fsse\",\n        \"--debug\"\n      ]\n```\n\n* 若要抑制默认日志输出，可添加 `--silent` 标志。这将阻止日志输出，除非同时传递了 `--debug` 标志。\n\n```json\n      \"args\": [\n        \"mcp-remote\",\n        \"https:\u002F\u002Fremote.mcp.server\u002Fsse\",\n        \"--silent\"\n      ]\n```\n\n* 若要为 mcp-remote 启用出站 HTTP(S) 代理，可添加 `--enable-proxy` 标志。启用后，mcp-remote 将使用常见的环境变量中的代理设置（例如 `HTTP_PROXY`、`HTTPS_PROXY` 和 `NO_PROXY`）。\n\n```json\n    \"args\": [\n      \"mcp-remote\",\n      \"https:\u002F\u002Fremote.mcp.server\u002Fsse\",\n      \"--enable-proxy\"\n    ],\n    \"env\": {\n      \"HTTPS_PROXY\": \"http:\u002F\u002F127.0.0.1:3128\",\n      \"NO_PROXY\": \"localhost,127.0.0.1\"\n    }\n```\n\n* 若要忽略远程服务器上的特定工具，可添加 `--ignore-tool` 标志。这会从 `tools\u002Flist` 响应中过滤掉与指定模式匹配的工具，并阻止 `tools\u002Fcall` 请求。支持使用 `*` 通配符模式。\n\n```json\n      \"args\": [\n        \"mcp-remote\",\n        \"https:\u002F\u002Fremote.mcp.server\u002Fsse\",\n        \"--ignore-tool\",\n        \"delete*\",\n        \"--ignore-tool\",\n        \"remove*\"\n      ]\n```\n\n您可以指定多个 `--ignore-tool` 标志来忽略不同的模式。示例：\n- `delete*`：忽略所有以“delete”开头的工具（如 `deleteTask`、`deleteUser`）\n- `*account`：忽略所有以“account”结尾的工具（如 `getAccount`、`updateAccount`）\n- `exactTool`：仅忽略名为“exactTool”的工具\n\n* 若要更改 OAuth 回调的超时时间（默认为 `30` 秒），可添加 `--auth-timeout` 标志，并指定以秒为单位的值。这在服务器端认证过程耗时较长时非常有用。\n\n```json\n      \"args\": [\n        \"mcp-remote\",\n        \"https:\u002F\u002Fremote.mcp.server\u002Fsse\",\n        \"--auth-timeout\",\n        \"60\"\n      ]\n```\n\n### 传输策略\n\nMCP Remote 在连接到 MCP 服务器时支持不同的传输策略。这使您可以控制是使用 Server-Sent Events (SSE) 还是 HTTP 传输，以及尝试它们的顺序。\n\n通过 `--transport` 标志指定传输策略：\n\n```bash\nnpx mcp-remote https:\u002F\u002Fexample.remote\u002Fserver --transport sse-only\n```\n\n**可用策略：**\n\n- `http-first`（默认）：首先尝试 HTTP 传输，若 HTTP 返回 404 错误，则回退到 SSE。\n- `sse-first`：首先尝试 SSE 传输，若 SSE 返回 405 错误，则回退到 HTTP。\n- `http-only`：仅使用 HTTP 传输，若服务器不支持则失败。\n- `sse-only`：仅使用 SSE 传输，若服务器不支持则失败。\n\n### 静态 OAuth 客户端元数据\n\nMCP Remote 支持提供静态 OAuth 客户端元数据，而不是使用 mcp-remote 的默认值。这在连接到期望特定客户端\u002F软件 ID 或范围的 OAuth 服务器时非常有用。\n\n可通过 JSON 字符串或以 `@` 为前缀的文件路径形式，使用 `--static-oauth-client-metadata` 标志提供客户端元数据：\n\n```bash\nnpx mcp-remote https:\u002F\u002Fexample.remote\u002Fserver --static-oauth-client-metadata '{ \"scope\": \"space separated scopes\" }'\n# 使用 node readfile，因此如果您不确定当前工作目录，最好使用绝对路径\nnpx mcp-remote https:\u002F\u002Fexample.remote\u002Fserver --static-oauth-client-metadata '@\u002FUsers\u002Fusername\u002FLibrary\u002FApplication Support\u002FClaude\u002Foauth_client_metadata.json'\n```\n\n### 静态 OAuth 客户端信息\n\n根据 [规范](https:\u002F\u002Fmodelcontextprotocol.io\u002Fspecification\u002F2025-03-26\u002Fbasic\u002Fauthorization#2-4-dynamic-client-registration)，服务器被鼓励但并非强制要求支持 [OAuth 动态客户端注册](https:\u002F\u002Fdatatracker.ietf.org\u002Fdoc\u002Fhtml\u002Frfc7591)。\n\n对于这些服务器，MCP Remote 支持提供静态 OAuth 客户端信息。这在连接到需要预先注册客户端的 OAuth 服务器时非常有用。\n\n可通过 JSON 字符串或以 `@` 为前缀的文件路径形式，使用 `--static-oauth-client-info` 标志提供客户端信息：\n\n```bash\nexport MCP_REMOTE_CLIENT_ID=xxx\nexport MCP_REMOTE_CLIENT_SECRET=yyy\nnpx mcp-remote https:\u002F\u002Fexample.remote\u002Fserver --static-oauth-client-info \"{ \\\"client_id\\\": \\\"$MCP_REMOTE_CLIENT_ID\\\", \\\"client_secret\\\": \\\"$MCP_REMOTE_CLIENT_SECRET\\\" }\"\n# 使用 node readfile，因此如果您不确定当前工作目录，最好使用绝对路径\nnpx mcp-remote https:\u002F\u002Fexample.remote\u002Fserver --static-oauth-client-info '@\u002FUsers\u002Fusername\u002FLibrary\u002FApplication Support\u002FClaude\u002Foauth_client_info.json'\n```\n\n### Claude Desktop\n\n[官方文档](https:\u002F\u002Fmodelcontextprotocol.io\u002Fquickstart\u002Fuser)\n\n要将 MCP 服务器添加到 Claude Desktop，您需要编辑位于以下位置的配置文件：\n\n* macOS：`~\u002FLibrary\u002FApplication Support\u002FClaude\u002Fclaude_desktop_config.json`\n* Windows：`%APPDATA%\\Claude\\claude_desktop_config.json`\n\n如果该文件尚未存在，您可能需要在“设置 > 开发者”中启用它，以添加文件系统 MCP 服务器。\n\n重启 Claude Desktop 以使配置文件中的更改生效。重启后，您应该会在输入框的右下角看到一个锤子图标。\n\n### Cursor\n\n[官方文档](https:\u002F\u002Fdocs.cursor.com\u002Fcontext\u002Fmodel-context-protocol)。配置文件位于 `~\u002F.cursor\u002Fmcp.json`。\n\n自版本 `0.48.0` 起，Cursor 直接支持未认证的 SSE 服务器。如果你的 MCP 服务器使用的是官方的 MCP OAuth 授权协议，则仍需添加一个 **\"command\"** 服务器并调用 `mcp-remote`。\n\n### Windsurf\n\n[官方文档](https:\u002F\u002Fdocs.codeium.com\u002Fwindsurf\u002Fmcp)。配置文件位于 `~\u002F.codeium\u002Fwindsurf\u002Fmcp_config.json`。\n\n## 构建远程 MCP 服务器\n\n有关构建和部署远程 MCP 服务器（包括作为有效的 OAuth 客户端）的说明，请参阅以下资源：\n\n* https:\u002F\u002Fdevelopers.cloudflare.com\u002Fagents\u002Fguides\u002Fremote-mcp-server\u002F\n\n特别是：\n\n* https:\u002F\u002Fgithub.com\u002Fcloudflare\u002Fworkers-oauth-provider：用于在 Cloudflare Workers 中定义符合 MCP 标准的 OAuth 服务器。\n* https:\u002F\u002Fgithub.com\u002Fcloudflare\u002Fagents\u002Ftree\u002Fmain\u002Fexamples\u002Fmcp：使用 [`agents`](https:\u002F\u002Fnpmjs.com\u002Fpackage\u002Fagents) 框架定义 `McpAgent`。\n\n有关测试这些服务器的更多信息，请参阅：\n\n* https:\u002F\u002Fdevelopers.cloudflare.com\u002Fagents\u002Fguides\u002Ftest-remote-mcp-server\u002F\n\n你知道更多想分享的资源吗？请将其添加到此 README 并提交 PR！\n\n## 故障排除\n\n### 清除 `~\u002F.mcp-auth` 目录\n\n`mcp-remote` 会将所有凭据信息存储在 `~\u002F.mcp-auth` 目录中（或你设置的 `MCP_REMOTE_CONFIG_DIR` 所指向的目录）。如果问题持续存在，可以尝试运行以下命令：\n\n```sh\nrm -rf ~\u002F.mcp-auth\n```\n\n然后重新启动你的 MCP 客户端。\n\n### 检查 Node.js 版本\n\n确保你安装的 Node.js 版本为 [18 或更高](https:\u002F\u002Fmodelcontextprotocol.io\u002Fquickstart\u002Fserver)。Claude Desktop 将使用系统自带的 Node.js 版本，即使你在其他地方安装了更新的版本。\n\n### 重启 Claude\n\n修改 `claude_desktop_config.json` 后，完全重启 Claude 可能会有帮助。\n\n### VPN 证书\n\n如果你通过 VPN 使用网络，可能会遇到问题。你可以尝试设置 `NODE_EXTRA_CA_CERTS` 环境变量，使其指向 CA 证书文件。如果使用 `claude_desktop_config.json`，配置可能如下所示：\n\n```json\n{\n \"mcpServers\": {\n    \"remote-example\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"mcp-remote\",\n        \"https:\u002F\u002Fremote.mcp.server\u002Fsse\"\n      ],\n      \"env\": {\n        \"NODE_EXTRA_CA_CERTS\": \"{your CA certificate file path}.pem\"\n      }\n    }\n  }\n}\n```\n\n### 检查日志\n\n* [实时跟踪 Claude Desktop 日志](https:\u002F\u002Fmodelcontextprotocol.io\u002Fdocs\u002Ftools\u002Fdebugging#debugging-in-claude-desktop)\n* macOS \u002F Linux：\u003Cbr\u002F>`tail -n 20 -F ~\u002FLibrary\u002FLogs\u002FClaude\u002Fmcp*.log`\n* 在 WSL 上使用 bash 时：\u003Cbr\u002F>`tail -n 20 -f \"C:\\Users\\YourUsername\\AppData\\Local\\Claude\\Logs\\mcp.log\"`\n* PowerShell：\u003Cbr\u002F>`Get-Content \"C:\\Users\\YourUsername\\AppData\\Local\\Claude\\Logs\\mcp.log\" -Wait -Tail 20`\n\n## 调试\n\n### 调试日志\n\n对于复杂的故障排除，尤其是与令牌刷新或身份验证相关的问题，可以使用 `--debug` 标志：\n\n```json\n\"args\": [\n  \"mcp-remote\",\n  \"https:\u002F\u002Fremote.mcp.server\u002Fsse\",\n  \"--debug\"\n]\n```\n\n这将在 `~\u002F.mcp-auth\u002F{server_hash}_debug.log` 中生成详细的日志文件，包含时间戳以及连接和身份验证过程每一步的完整信息。当遇到令牌刷新、笔记本电脑休眠\u002F唤醒或身份验证问题时，请在寻求支持时提供这些日志。\n\n### 身份验证错误\n\n如果从 `\u002Fcallback` URL 返回以下错误：\n\n```\nAuthentication Error\nToken exchange failed: HTTP 400\n```\n\n可以运行 `rm -rf ~\u002F.mcp-auth` 来清除本地存储的状态和令牌。\n\n### “客户端”模式\n\n在命令行中运行以下命令（而非从 MCP 服务器运行）：\n\n```shell\nnpx -p mcp-remote@latest mcp-remote-client https:\u002F\u002Fremote.mcp.server\u002Fsse\n```\n\n这将完成整个授权流程，并尝试列出远程 URL 上的工具和资源。建议在运行 `rm -rf ~\u002F.mcp-auth` 后执行此操作，以确认问题是否由过期的凭据引起；否则，这些日志应该比 MCP 客户端中的日志更清晰地显示问题所在。","# mcp-remote 快速上手指南\n\n`mcp-remote` 是一个实验性工具，用于将仅支持本地（stdio）连接的 MCP 客户端连接到远程 MCP 服务器，并支持 OAuth 认证。它解决了当前主流客户端（如 Claude Desktop、Cursor）尚未完全支持远程授权协议的问题。\n\n## 环境准备\n\n*   **操作系统**：macOS, Windows, Linux\n*   **Node.js**：版本需为 **18 或更高**。\n    *   检查版本命令：`node -v`\n    *   如未安装或版本过低，请访问 [Node.js 官网](https:\u002F\u002Fnodejs.org\u002F) 下载最新版。\n*   **前置依赖**：确保系统已安装 `npx`（通常随 Node.js 自动安装）。\n*   **网络要求**：能够访问目标远程 MCP 服务器地址。如需通过代理访问，需在配置中启用 `--enable-proxy` 并设置环境变量。\n\n> **提示**：国内开发者若遇到 `npx` 下载缓慢问题，可临时配置 npm 镜像源：\n> ```bash\n> npm config set registry https:\u002F\u002Fregistry.npmmirror.com\n> ```\n\n## 安装步骤\n\n`mcp-remote` 无需全局安装，推荐通过 `npx` 直接在配置文件中按需调用。这种方式可以避免显式的安装步骤，并确保每次运行都使用最新或指定版本的代码。\n\n如果在执行过程中遇到确认安装的提示错误，可在参数中添加 `-y` 自动确认。\n\n## 基本使用\n\n大多数主流 MCP 客户端（Claude Desktop, Cursor, Windsurf）均使用 JSON 格式进行配置。你需要编辑对应的配置文件，添加一个指向远程服务器的 `mcpServers` 条目。\n\n### 1. 基础配置示例\n\n以下配置将本地的 stdio 请求桥接到远程 SSE 服务器：\n\n```json\n{\n  \"mcpServers\": {\n    \"remote-example\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"mcp-remote\",\n        \"https:\u002F\u002Fremote.mcp.server\u002Fsse\"\n      ]\n    }\n  }\n}\n```\n\n### 2. 带认证头的配置（推荐）\n\n如果远程服务器需要自定义 Header（如 Bearer Token），请使用 `--header` 参数。\n\n**注意**：Cursor 和 Windows 版 Claude Desktop 存在参数转义 bug，建议将空格放在环境变量中，而非直接写在 args 里：\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"remote-example\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"mcp-remote\",\n        \"https:\u002F\u002Fremote.mcp.server\u002Fsse\",\n        \"--header\",\n        \"Authorization:${AUTH_HEADER}\" \n      ],\n      \"env\": {\n        \"AUTH_HEADER\": \"Bearer \u003Cyour-auth-token>\" \n      }\n    }\n  }\n}\n```\n\n### 3. 多实例隔离\n\n如果需要连接同一个远程服务的不同租户（例如不同的 Atlassian 租户），请使用 `--resource` 参数来隔离 OAuth 会话：\n\n```json\n{\n  \"mcpServers\": {\n    \"atlassian_tenant1\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"mcp-remote\",\n        \"https:\u002F\u002Fmcp.atlassian.com\u002Fv1\u002Fsse\",\n        \"--resource\",\n        \"https:\u002F\u002Ftenant1.atlassian.net\u002F\"\n      ]\n    }\n  }\n}\n```\n\n### 4. 常用客户端配置文件路径\n\n配置完成后，请重启对应的客户端以生效：\n\n*   **Claude Desktop**:\n    *   macOS: `~\u002FLibrary\u002FApplication Support\u002FClaude\u002Fclaude_desktop_config.json`\n    *   Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n    *   *注：如文件不存在，需在设置中开启 Developer 模式。*\n*   **Cursor**: `~\u002F.cursor\u002Fmcp.json`\n*   **Windsurf**: `~\u002F.codeium\u002Fwindsurf\u002Fmcp_config.json`\n\n### 5. 进阶参数速查\n\n在 `args` 数组中追加以下参数可实现更多功能：\n\n*   **强制更新**：使用 `mcp-remote@latest` 代替 `mcp-remote`。\n*   **修改回调端口**：在 URL 后添加端口号，例如 `\"9696\"`（默认 3334）。\n*   **允许 HTTP**：在内网可信环境下添加 `\"--allow-http\"`。\n*   **调试模式**：添加 `\"--debug\"`，日志将写入 `~\u002F.mcp-auth\u002F{server_hash}_debug.log`。\n*   **忽略特定工具**：添加 `\"--ignore-tool\", \"delete*\"` 可过滤匹配的工具。\n*   **传输策略**：添加 `\"--transport\", \"sse-only\"` 强制使用 SSE（默认为 `http-first`）。","某 SaaS 团队希望让使用 Claude Desktop 和 Cursor 的开发者直接访问部署在云端的 Atlassian MCP 服务，以统一管理和迭代功能。\n\n### 没有 mcp-remote 时\n- 主流客户端仅支持本地 stdio 传输，无法直接连接远程 HTTP+SSE 服务器，导致云端服务无法被调用。\n- 若强行在用户本地运行服务代码，不仅增加了环境配置负担，还迫使敏感 API 密钥暴露在用户机器上，存在安全隐患。\n- 每次修复漏洞或更新功能时，必须通知所有用户手动升级本地包，无法实现“一次部署，全员生效”的敏捷迭代。\n- 面对多个租户（如不同 Atlassian 实例）时，缺乏隔离机制，难以在同一客户端内管理独立的 OAuth 会话和令牌。\n\n### 使用 mcp-remote 后\n- 通过简单的 npx 命令配置，mcp-remote 充当桥梁，让仅支持本地的客户端也能无缝连接经过身份验证的远程 MCP 服务器。\n- 核心业务逻辑保留在云端，用户无需在本地安装复杂依赖，API 密钥等机密信息也无需离开服务器，大幅提升了安全性。\n- 团队可随时推送后端更新，所有开发者下次启动客户端时即自动获取最新功能，彻底消除了分发更新的摩擦。\n- 利用 `--resource` 标志，mcp-remote 能为不同租户隔离 OAuth 会话，轻松在同一编辑器中切换和管理多个企业环境。\n\nmcp-remote 的核心价值在于它打破了本地客户端的限制，让开发者能在享受本地工具便利的同时，安全、高效地利用云端服务的强大能力与敏捷性。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fgeelen_mcp-remote_4c3ba71a.png","geelen","Glen Maddern","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002Fgeelen_6193f838.jpg","Melbourne\u002FNaarm","glenmaddern@gmail.com","https:\u002F\u002Fglenmaddern.com","https:\u002F\u002Fgithub.com\u002Fgeelen",[84,88],{"name":85,"color":86,"percentage":87},"TypeScript","#3178c6",92.1,{"name":89,"color":90,"percentage":91},"JavaScript","#f1e05a",7.9,1360,223,"2026-04-08T02:14:25","MIT","macOS, Windows, Linux","未说明",{"notes":99,"python":97,"dependencies":100},"该工具是一个基于 Node.js 的命令行实用程序，用于将仅支持本地 stdio 传输的 MCP 客户端连接到远程 MCP 服务器。主要依赖 Node.js 环境（版本需 18 或更高），通过 npx 直接运行无需显式安装。配置时需修改各客户端（如 Claude Desktop, Cursor, Windsurf）的 JSON 配置文件。凭证信息默认存储在 ~\u002F.mcp-auth 目录中。支持 OAuth 认证流程，需在本地开放端口（默认 3334）用于回调。",[101,102],"Node.js >= 18","npx (npm package runner)",[13],"2026-03-27T02:49:30.150509","2026-04-08T14:45:32.160831",[107,112,117,122,127,132],{"id":108,"question_zh":109,"answer_zh":110,"source_url":111},24616,"mcp-remote 是否支持 MCP 规范中的流式传输（Streaming）功能？","是的，流式 HTTP 支持（Streaming HTTP support）已经在 `v0.1.x` 版本发布中实现。用户可以更新到该版本或更高版本来体验流式传输功能。","https:\u002F\u002Fgithub.com\u002Fgeelen\u002Fmcp-remote\u002Fissues\u002F14",{"id":113,"question_zh":114,"answer_zh":115,"source_url":116},24612,"为什么无法同时运行多个 mcp-remote 服务器实例？","这是由于 mcp-remote 的认证协调机制导致的。第一个实例会创建锁文件并占用回调端口，导致后续实例等待认证。解决方案包括：\n1. 对于支持原生 SSE 的客户端（如 Claude Code），可以直接配置 SSE 连接而无需使用 mcp-remote 代理，从而为每个实例建立独立的 OAuth 会话。\n2. 确保不同终端使用的回调端口不冲突（虽然工具会自动选择，但锁文件机制仍可能阻塞）。\n3. 如果问题持续，尝试关闭所有实例并清理可能的残留锁文件后重试。","https:\u002F\u002Fgithub.com\u002Fgeelen\u002Fmcp-remote\u002Fissues\u002F25",{"id":118,"question_zh":119,"answer_zh":120,"source_url":121},24613,"遇到 \"fetch is not defined\" 错误导致 SSE 连接随机失败怎么办？","这通常是因为系统中安装了过旧版本的 Node.js，而某些客户端（如 Claude Code）可能会错误地调用这些旧版本。解决方法是：\n1. 检查并删除 nvm（Node Version Manager）中所有过旧的 Node.js 版本。\n2. 确保默认使用的 Node.js 版本较新（如 v22+）。\n3. 如果不想删除旧版本，可以尝试在配置中指定 `npx` 的绝对路径来强制使用正确版本的 Node。","https:\u002F\u002Fgithub.com\u002Fgeelen\u002Fmcp-remote\u002Fissues\u002F16",{"id":123,"question_zh":124,"answer_zh":125,"source_url":126},24614,"遇到 \"Key Symbol(headers list) ... cannot be converted to a ByteString\" 错误如何解决？","这是一个与特定 Node.js 版本或 mcp-remote 版本兼容性相关的问题。有效的解决方案包括：\n1. 升级 Node.js 到最新版本（有用户反馈升级到 v24.7.0 解决了问题）。\n2. 如果升级 Node 无效，尝试回退 mcp-remote 到之前的稳定版本，例如使用命令：`npx -y mcp-remote@0.1.25 \u003Curl>`。","https:\u002F\u002Fgithub.com\u002Fgeelen\u002Fmcp-remote\u002Fissues\u002F148",{"id":128,"question_zh":129,"answer_zh":130,"source_url":131},24615,"更新后初始化时发送 POST 请求而不是 GET 请求导致连接失败怎么办？","这是因为新版本默认尝试使用可流式传输的 HTTPS 传输（Streamable HTTP），而某些服务器可能仅支持 SSE。解决方法是显式指定传输协议：\n在运行命令时添加 `--transport sse-only` 或 `--transport sse-first` 参数，强制工具使用 SSE 协议进行连接。例如：`npx mcp-remote --transport sse-only \u003Curl>`。","https:\u002F\u002Fgithub.com\u002Fgeelen\u002Fmcp-remote\u002Fissues\u002F47",{"id":133,"question_zh":134,"answer_zh":135,"source_url":116},24617,"如何在多个 MCP 客户端中配置多个 Atlassian 实例以避免冲突？","推荐使用支持原生 SSE 的客户端（如 Claude Code），直接在配置文件中定义多个服务器，每个服务器指向相同的 URL 但拥有独立的配置块。这样客户端会为每个实例管理独立的 OAuth 会话，避免 mcp-remote 代理带来的锁文件冲突。示例配置 (`~\u002F.claude.json`)：\n```json\n{\n  \"mcpServers\": {\n    \"atlassian_slalom\": {\n      \"type\": \"sse\",\n      \"url\": \"https:\u002F\u002Fmcp.atlassian.com\u002Fv1\u002Fsse\"\n    },\n    \"atlassian_plusgrade\": {\n      \"type\": \"sse\",\n      \"url\": \"https:\u002F\u002Fmcp.atlassian.com\u002Fv1\u002Fsse\"\n    }\n  }\n}\n```",[]]