> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirobody.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Mirobody MCP Server

> 将 Mirobody 的工具连接到 Claude、Cursor、ChatGPT 等 MCP 客户端

## 概览

Mirobody 可作为**支持 OAuth 的 MCP Server**，把它的 [内置工具](/zh/tools/built-in) 暴露给 Claude Desktop、Cursor 以及自定义 MCP 客户端等 AI 客户端。该端点使用 **JSON-RPC 2.0**，由 `src/mcp/` 提供。

<Info>
  Model Context Protocol（MCP）是 AI 应用访问工具、resources 与上下文的标准接口。
</Info>

引擎对外暴露两条请求路径：

```
http://localhost:8080/mcp                 # authenticates via bearer JWT
http://localhost:8080/mcp/{secret}        # personal-MCP secret resolving to a user
```

<Note>
  独立二进制监听 `HTTP_HOST:HTTP_PORT`，默认为 `0.0.0.0:8080`。如果你改了 `HTTP_PORT`，请相应调整下文的端口。
</Note>

## MCP 配置

### For Claude Desktop & Cursor

将 Mirobody 添加到你的 MCP 配置中：

```json ~/Library/Application Support/Claude/claude_desktop_config.json theme={null}
{
  "mcpServers": {
    "mirobody_mcp": {
      "command": "npx",
      "args": [
        "-y",
        "universal-mcp-proxy"
      ],
      "env": {
        "UMCP_ENDPOINT": "http://localhost:8080/mcp"
      }
    }
  }
}
```

<Tabs>
  <Tab title="macOS/Linux">
    配置文件位置：

    ```bash theme={null}
    ~/Library/Application Support/Claude/claude_desktop_config.json
    ```

    对于 Cursor：

    ```bash theme={null}
    ~/.cursor/mcp_config.json
    ```
  </Tab>

  <Tab title="Windows">
    配置文件位置：

    ```powershell theme={null}
    %APPDATA%\Claude\claude_desktop_config.json
    ```

    对于 Cursor：

    ```powershell theme={null}
    %USERPROFILE%\.cursor\mcp_config.json
    ```
  </Tab>
</Tabs>

### 重启客户端

更新配置后：

<Steps>
  <Step title="保存配置文件">
    确保对 MCP 配置文件的修改已保存
  </Step>

  <Step title="重启 Claude/Cursor">
    完全关闭并重新打开 Claude Desktop 或 Cursor
  </Step>

  <Step title="验证连接">
    MCP server 应出现在客户端的 MCP servers 列表中

    在 Claude Desktop：点击 MCP 图标查看已连接 servers

    在 Cursor：在 settings 中查看 MCP 状态
  </Step>

  <Step title="测试一个工具">
    尝试使用你的某个工具：

    "我最近睡得怎么样？"

    客户端应调用 `family_health` 工具。（一个无需 auth 的连通性测试：让它 `echo` 一段文本。）
  </Step>
</Steps>

<Check>
  你应该能在 AI 客户端中看到可用的 Mirobody 工具！
</Check>

## 认证流程

通过 MCP 客户端使用工具时，OAuth 认证会自动处理：

<Frame>
  <img src="https://mintcdn.com/thetahealth/XPteEwyWLNYyOt7h/images/mcp-sequence.svg?fit=max&auto=format&n=XPteEwyWLNYyOt7h&q=85&s=716cfafd705924dbfec078a04ea2f1be" alt="MCP request flow: user -> client -> MCP -> Mirobody -> answer" data-og-width="1000" width="1000" data-og-height="110" height="110" data-path="images/mcp-sequence.svg" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/thetahealth/XPteEwyWLNYyOt7h/images/mcp-sequence.svg?w=280&fit=max&auto=format&n=XPteEwyWLNYyOt7h&q=85&s=3c97ef9df96b61c4f112b92aa2632948 280w, https://mintcdn.com/thetahealth/XPteEwyWLNYyOt7h/images/mcp-sequence.svg?w=560&fit=max&auto=format&n=XPteEwyWLNYyOt7h&q=85&s=8d2663f650107ec26690162e0e397e62 560w, https://mintcdn.com/thetahealth/XPteEwyWLNYyOt7h/images/mcp-sequence.svg?w=840&fit=max&auto=format&n=XPteEwyWLNYyOt7h&q=85&s=4168d0178e485cac25a0b9747a016eee 840w, https://mintcdn.com/thetahealth/XPteEwyWLNYyOt7h/images/mcp-sequence.svg?w=1100&fit=max&auto=format&n=XPteEwyWLNYyOt7h&q=85&s=eb7a06293bf6d2496b587516c7dec631 1100w, https://mintcdn.com/thetahealth/XPteEwyWLNYyOt7h/images/mcp-sequence.svg?w=1650&fit=max&auto=format&n=XPteEwyWLNYyOt7h&q=85&s=eac517a26f968c337f9d775908024a9b 1650w, https://mintcdn.com/thetahealth/XPteEwyWLNYyOt7h/images/mcp-sequence.svg?w=2500&fit=max&auto=format&n=XPteEwyWLNYyOt7h&q=85&s=0aad55b0a21a86a7a7c83301b4f26a37 2500w" />
</Frame>

<Note>
  OAuth token 由 Mirobody 管理。用户只需认证一次，工具即可安全访问其数据。
</Note>

## 可用 Endpoints

MCP server 暴露以下 endpoint：

**Base URL**: `http://localhost:8080/mcp`（或 `http://localhost:8080/mcp/{secret}` 用于个人 MCP secret）

**Protocol**: JSON-RPC 2.0

**Methods** 包括：

* `tools/list`: 列出所有可用工具
* `tools/call`: 执行指定工具

## 面向 ChatGPT

Mirobody 也可以作为 GPT app 运行，在 ChatGPT 内启用相关能力。更多内容请阅读 [ChatGPT Apps](/zh/tools/chatgpt-apps)。

## 自定义 MCP 客户端

### 直接 HTTP 请求

你可以通过 HTTP 直接调用工具：

```bash theme={null}
# List all tools
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

# Call a tool (auth-scoped tools need a bearer JWT)
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "family_health",
      "arguments": { "member": "me", "count": 20 }
    }
  }'
```

## 下一步

<CardGroup cols={2}>
  <Card title="内置工具" icon="wrench" href="/zh/tools/built-in">
    浏览默认提供的健康工具
  </Card>

  <Card title="添加自定义工具" icon="plus" href="/zh/tools/adding-tools">
    创建你自己的工具
  </Card>

  <Card title="MCP API 参考" icon="book" href="/zh/api-reference/mcp-servers">
    详细的 MCP 协议文档
  </Card>
</CardGroup>