MateMCP

MateMCP

你的 Agent 达到使用上限了？继续工作。

网站： matemcp.com · 账户门户： api.matemcp.com · 发布版本： agent-latest

MateMCP 帮你从已付费的 AI 套餐中完成更多有用的工作。当服务提供商内置的编码或 Agent 工具达到使用上限，但 AI 聊天本身仍可用时，MateMCP 会为该对话提供一条受控通道，连接到你自己的 Windows 或 macOS 电脑，让你能继续在真实项目和工具上推进有用的工作。

MateMCP 不会提高或绕过服务提供商的使用配额。 它通过 MCP 为兼容的 AI 客户端提供另一种工作方式，使用你的设备和访问规则。

使用你自己的 AI。将 ChatGPT、Claude、Grok 或其他兼容的 MCP 客户端连接到已注册的 MateMCP Agent。Agent 可以使用项目文件、Shell、浏览器、桌面应用、附件、密钥和持久项目上下文，同时 MateMCP 会对访问进行范围限制、身份验证、可观测化，并支持审批。

matemcp.com 上的公开网站提供产品信息和入门指引。经过身份验证的账户门户 api.matemcp.com 负责账户访问、已注册设备、审批和管理。日常桌面使用体验依然简单：安装 MateMCP Desktop，注册设备，将其 MCP URL 复制到 AI 客户端，然后通过 OAuth 授权。你无需复制 Agent 凭据，也无需将本地端口暴露到互联网。

为什么选择 MateMCP？

• 内置 Agent 停止工作时，继续推进 —— 如果聊天仍可用，就为它提供一条受控通道，让它访问你自己的工具，而不是结束工作会话。
• 充分利用已有的 AI 套餐 —— 将高性能聊天时间用于实际的本地工作，无需 MateMCP 替代你的 AI 服务提供商。
• 使用你自己的 AI —— 使用 ChatGPT、Claude、Grok 或其他兼容的 MCP 客户端，并采用相同的本地 Agent 模式。
• 在真实设备上工作 —— 文件、Shell、浏览器、桌面应用、附件和项目上下文都存放在你日常工作的地方。
• 保持掌控 —— 通过项目范围限制、OAuth、审批、可审计性和本地密钥处理，明确控制强大权限的使用。

MateMCP 能做什么？

• 限定项目范围的文件系统访问 —— 仅在已配置的项目中读取和修改文件。
• Shell 和交互式终端会话 —— 运行命令、保持长期运行的 Shell、在短暂断连后恢复输出，并注入已批准的密钥而不向 AI 公开。
• 电脑操作 —— 查看屏幕截图，与浏览器或原生 UI 交互，点击、输入、滚动，并在支持的环境中使用语义化无障碍操作。
• 浏览器自动化和视觉 QA —— 浏览应用、检查响应式布局、截取屏幕截图，并支持前端和桌面验证工作流。
• 安全附件传输 —— 使用有上限、可恢复且经过完整性校验的传输方式，将对话文件上传到选定的 Agent。
• 审批 —— 对敏感操作要求本地或远程审批，并确保决策可审计。
• 密钥管理器 —— 将用户管理的凭据保存在操作系统凭据存储中，而不是模型上下文或项目文件里。
• 活动记录、审计和诊断 —— 查看 Agent 正在执行的操作，检查审批和凭据活动，并诊断连接或执行故障。
• 技能与记忆 —— 在 Agent 中保存跨项目的全局知识；项目专属知识则保存在版本化的仓库 SKILL.md 文件中，并随 Git 一起迁移。
• 多设备访问 —— 在一个账户下注册多个可单独撤销的 Agent。
• 弹性连接 —— 逻辑会话可在 Agent 或 Relay 短暂断连后继续，操作使用稳定标识，支持的流和传输可以安全恢复。

工作原理

flowchart LR
    User[User / Admin]
    Site[Public website\nmatemcp.com]
    Portal[Account portal\napi.matemcp.com]
    AI[AI client\nChatGPT / Claude / Grok / MCP client]
    Relay[MateMCP Relay]
    API[OAuth Control Plane]
    Agent[Local MateMCP Agent]
    Companion[Companion]
    Machine[Projects · Shell · Browser · Desktop · Secrets]

    User --> Site
    User --> Portal
    Portal -->|account / devices / approvals / admin| API
    AI -->|OAuth + MCP| Relay
    AI -->|Authorize| API
    Relay <-->|resilient Agent channel| Agent
    Agent --> Machine
    Companion <-->|local management| Agent
    Companion -->|approvals / status / logs| Machine
    Relay -->|authorization checks| API

公共网站介绍产品并提供入门入口。账户门户是基于浏览器的用户／管理员界面，用于管理账户、设备、审批和各项管理操作。Relay 将远程 MCP 流量转发给正确的在线 Agent。Control Plane 负责账户、Agent 归属关系、OAuth、授权和远程审批协调。Agent 在本地执行任务。Companion 为用户提供原生界面，用于查看状态、审批、Shell、密钥、活动、诊断信息、更新，并控制 Agent 生命周期。

信任与安全模型

MateMCP 旨在作为 AI 与用户电脑之间的边界，而不是绕过本地安全机制的隧道。

• 每个 Agent 都有随机生成的公共 ID 和独立的高熵私有凭据。
• Agent 凭据和用户管理的密钥存储在 macOS Keychain 或 Windows Credential Manager 中。
• MCP URL 用于标识 Agent；它本身不是 Agent 的私有凭据。
• OAuth 令牌绑定到用户、Agent／资源和已授予的权限范围。访问令牌可刷新，无需反复要求用户重新连接。
• 文件系统访问限制在已配置的项目根目录内。
• mcp:read、mcp:write 和 mcp:shell 功能会受到强制执行，而不是根据 URL 推断。
• 敏感操作可要求明确审批；审批和凭据使用均可审计。
• Relay 无需访问用户的操作系统机密。
• 附件传输需经审批，具有限额、可恢复，并可选择使用 SHA-256 验证。
• Agent 和 Relay 重连时会使用稳定的会话／操作标识，以减少临时故障后产生重复副作用的情况。

详细模型请参阅 docs/security.md 和 docs/approval.md。

快速开始

1. 在 api.matemcp.com 创建 MateMCP 账户或登录。
2. 使用以下命令之一为电脑安装 MateMCP Desktop。
3. 打开 Companion，并在出现提示时完成设备注册。
4. 复制 Agent 专属的 MCP URL，例如 https://relay.matemcp.com/mcp/agt_...。
5. 将该 URL 添加到 ChatGPT、Claude、Grok 或其他支持 MCP 的 AI 客户端。
6. 使用拥有该 Agent 的同一个 MateMCP 账户完成 OAuth。
7. 尝试一个安全的首个任务，例如让 AI 列出已配置的项目或检查某个文件。
8. 如果敏感操作需要同意，请在 Companion 或账户门户中查看审批。

**Agent 更新添加或更改 MCP 工具后：**某些客户端可能会保留之前的工具快照。对于 ChatGPT，请参阅 Agent 更新后刷新 ChatGPT MCP 工具。

安装／升级 MateMCP Desktop

macOS

适用于 Apple Silicon Mac：

curl -fsSL https://raw.githubusercontent.com/vrassouli/MateMCP/main/scripts/bootstrap-macos.sh | bash

引导脚本会原位安装或升级 Agent + Companion、启动 Agent，并在需要时打开 Companion 进行交互式设置，同时保留现有配置和安全凭据。

手动安装包：适用于 macOS Apple Silicon 的 MateMCP Desktop · 最新稳定版本

Agent 以每用户 LaunchAgent 的形式运行。Companion 安装在 ~/Applications/MateMCP Agent Companion.app 下。私有配置位于 ~/Library/Application Support/MateMCP 下；凭据和密钥使用 macOS Keychain。

Computer Use 需要相应的 macOS 辅助功能和屏幕录制权限。生产环境的签名／TCC 身份强化仍在改进中，因此在某些更新后，开发版／临时签名构建可能需要重新授予权限。

Windows

从 PowerShell 运行：

irm https://raw.githubusercontent.com/vrassouli/MateMCP/main/scripts/bootstrap-windows.ps1 | iex

在 Windows x64 上，bootstrap 会安装或升级 Agent + Companion，启动后台 Agent，在需要交互式设置时打开 Companion，并保留用户范围的配置和凭据。

手动安装包：适用于 Windows x64 的 MateMCP Desktop · 最新稳定版本

私有配置位于 %APPDATA%\MateMCP 下；已注册的凭据和机密信息使用 Windows Credential Manager。

平台状态

平台	Agent	原生 Companion	Computer Use / 视觉支持	备注
macOS Apple Silicon	✅	✅	✅	原生桌面语义操作和视觉工作流；需要 macOS 权限。
macOS Intel	✅	仅 Agent 安装包	部分支持	目前尚未发布适用于 Intel Mac 的 Companion。
Windows x64	✅	✅	✅	原生 Windows Graphics Capture 预览，另有截图回退方案。
Windows ARM64	✅	仅 Agent 安装包	部分支持	尚未为 ARM64 提供原生 WGC 辅助程序；仍可使用截图回退方案。

远程 MCP 客户端状态

客户端	当前验证情况
ChatGPT	主要经过端到端实测的远程 MCP 客户端。
Claude	已验证可通过公共 MateMCP Relay 成功连接；各客户端的具体功能表现仍可能有所不同。
Grok	已验证可通过公共 MateMCP Relay 成功连接；各客户端的具体功能表现仍可能有所不同。
其他 MCP 客户端	MateMCP 使用基于标准的 MCP/OAuth 接口；应针对每个客户端／服务提供商验证兼容性。

公共 Relay 的可访问性可能取决于客户端服务提供商所使用的网络路径。生产环境中的 MateMCP 部署可以在公共主机名前端使用 Cloudflare 或其他 HTTPS 边缘／反向代理，而无需更改面向 Agent 的 MCP URL 模式。

Companion 一览

Companion 是用户的本地控制界面。当前功能包括：

• Agent 启动／停止／重启和状态。
• MCP 端点查看与复制操作。
• 待处理的审批和策略管理。
• 交互式 Shell 会话。
• 由操作系统凭据存储支持的密钥管理器。
• 活动与审计历史记录。
• Agent 日志和诊断信息。
• 全局技能与记忆的查看和管理；项目技能是各个代码仓库中的普通版本控制文件。
• Computer Use 预览／状态。
• 使用期间防止休眠控制，并在 Agent 最近一次活动后提供 15 分钟的空闲宽限期。
• 手动检查更新，以及在受支持的平台上选择自动更新 Desktop。

账户门户一览

基于浏览器的账户门户 api.matemcp.com 是本地 Companion 的补充。当前门户功能包括：

• 登录和注册，以及常规账户／会话控制。
• 设备管理：管理已注册的设备，包括控制平面支持的状态和撤销／移除操作。
• 审批：查看后端支持的待处理操作以及近期／历史记录。
• 管理：供获授权的管理员使用，包括用户搜索／状态管理以及相应的设备管理。
• 对用户／管理员操作进行服务器端授权；敏感的 Agent 凭据和已存储的机密信息不会通过门户公开。

自托管 Web + 账户门户/API + Relay

对于常见的单服务器部署，使用以下唯一标准安装/更新命令：

curl -fsSL https://raw.githubusercontent.com/vrassouli/MateMCP/main/deploy/install.sh | sudo bash

安装程序可安全更新：它会保留现有配置，仅询问缺失的设置值，刷新当前 Compose 定义，拉取并重新创建公开的 Web、API 和 Relay 服务，保持私有 API↔Relay 凭据同步，并在报告成功前对服务进行健康检查。在受支持的 Debian/Ubuntu 主机上，如有需要，它还可以引导安装 Docker Engine + Compose。

仅当 Web、API 和 Relay 由不同组件分别管理时，才使用组件安装程序进行高级部署：

# Public product website
curl -fsSL https://raw.githubusercontent.com/vrassouli/MateMCP/main/deploy/web/install.sh | sudo bash

# API / Control Plane
curl -fsSL https://raw.githubusercontent.com/vrassouli/MateMCP/main/deploy/api/install.sh | sudo bash

# Relay
curl -fsSL https://raw.githubusercontent.com/vrassouli/MateMCP/main/deploy/relay/install.sh | sudo bash

API 支持 SQLite，用于小型单服务器部署；也支持 SQL Server，用于外部数据库部署。Web、API 和 Relay 应置于 HTTPS 反向代理之后；不得将其容器端口直接暴露到互联网。确保 matemcp.com、api.matemcp.com 和 relay.matemcp.com 分别路由到各自独立的后端。

外部身份提供商为可选项，且因部署而异。提供商配置、回调 URL 和账户关联行为详见 docs/external-login-providers.md；仅启用已为该部署配置并验证的提供商。

Cloudflare 为可选项。若将其用于 MateMCP 前端，请确保三个公开主机名分别独立路由，保留原始 HTTPS 主机名/协议，并且不要缓存经过身份验证的 API 响应。同样的部署模式也适用于其他 HTTPS 反向代理/边缘服务。

生产环境的主机名/TLS 路由详见 docs/production-web-deployment.md。Web 部署详情见 deploy/web/README.md，Relay 专属的反向代理指南见 deploy/relay/README.md。

文档

主题	文档
架构	docs/architecture.md
安全模型	docs/security.md
审批	docs/approval.md
Agent/平台功能对等性	docs/agent-feature-parity.md
计算机使用	docs/computer-use.md
桌面控制	docs/desktop-control.md
macOS 语义操作	docs/macos-semantic-actions.md
浏览器视觉 QA	docs/browser-visual-qa.md
附件传输	docs/attachment-transfer.md
交互式 Shell 密钥	docs/interactive-shell-secrets.md
凭据注入	docs/credential-injection.md
连通性/混沌测试覆盖	docs/connectivity-chaos-testing.md
ChatGPT 工具刷新	docs/chatgpt-tool-refresh.md
项目上下文与仓库 Skills	docs/project-context-bootstrap.md
生产环境 Web 部署	docs/production-web-deployment.md
外部登录提供商	docs/external-login-providers.md
开发工作流	docs/development-workflow.md
路线图	docs/roadmap.md

当前限制与正在进行的工作

MateMCP 正在积极开发中。部分领域目前仍有意采取保守策略，或仍在持续强化：

• Native Companion 的打包目前主要面向 Windows x64 和 macOS Apple Silicon。
• Windows ARM64 使用截图回退方案，而非原生 WGC 预览助手。
• macOS 生产签名和 TCC 身份仍需强化，以确保权限在每次生产更新后都能可靠保留。
• Global Skills & Memory 和仓库 Skills 目前已可用，但在不同 AI 客户端之间主动自动使用上下文的功能仍在演进中。
• ChatGPT 仍是主要的全端到端兼容性目标；Claude 和 Grok 的连接也已通过验证，但不同提供商的功能行为仍可能有所差异。
• Safe & Informed Approvals 正在扩展，以便审批对话框能够说明后果和风险，而不只是依赖原始命令语法。

发布版本

main 是稳定开发版本的事实来源。不断更新的 agent-latest 发布版本包含当前稳定的 Agent 软件包，以及适用于受支持架构的原生桌面软件包。诸如 v0.1.0 这样的版本标签会发布带版本号的发布资源。

欢迎通过 GitHub Issues 和 Pull Requests 提交贡献和实测报告。