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

# MCP 服务器

> 学习如何将 SUNRA 的 MCP 服务器与 Cursor、VS Code、Cline、Windsurf 和其他开发环境集成，实现无缝的 AI 模型访问。

# 设置 SUNRA MCP 服务器

SUNRA 模型上下文协议 (MCP) 服务器提供与流行开发环境的无缝集成，允许您直接从编辑器或 IDE 访问 SUNRA 的 AI 模型。本指南将引导您在各种工具中设置 MCP 服务器。

## 什么是 MCP？

模型上下文协议 (MCP) 是 AI 助手安全访问外部资源和工具的标准化方式。SUNRA MCP 服务器允许您：

* **列出和搜索 AI 模型**，可用于 SUNRA
* **提交请求**到任何模型端点
* **检查状态**并从队列系统检索结果
* **上传文件**并管理模型模式
* **管理 API 认证**无缝

## 先决条件

在设置 MCP 服务器之前，请确保您拥有：

1. **Node.js** 已安装（版本 18 或更高）
2. **SUNRA API 密钥**来自[您的控制台](https://sunra.ai/dashboard/api-tokens)
3. 您首选的编辑器/IDE 已安装

## 安装

SUNRA MCP 服务器可作为 npm 包使用：

```bash theme={null}
npm install -g @sunra/mcp-server
```

或直接使用 npx（推荐）：

```bash theme={null}
npx @sunra/mcp-server
```

## 按编辑器配置

### Cursor

Cursor 通过其配置文件支持 MCP。在项目根目录创建或更新 `.cursor/mcp.json`：

```json theme={null}
{
  "mcpServers": {
    "sunra-mcp-server": {
      "command": "npx",
      "args": ["@sunra/mcp-server"]
    }
  }
}
```

**用户设置中的替代全局配置**：

1. 打开Cursor设置
2. 导航到"MCP Servers"
3. 添加新服务器：
   * **Name**: `sunra-mcp-server`
   * **Command**: `npx`
   * **Args**: `@sunra/mcp-server`

### VS Code

对于支持 MCP 的 VS Code（需要兼容扩展）：

创建`.vscode/mcp.json`：

```json theme={null}
{
  "mcpServers": {
    "sunra-mcp-server": {
      "command": "npx",
      "args": ["@sunra/mcp-server"],
      "env": {
        "SUNRA_KEY": "your-api-key-here"
      }
    }
  }
}
```

### Cline

Cline 通过其设置支持 MCP 服务器。添加到您的 Cline 配置：

```json theme={null}
{
  "mcpServers": {
    "sunra": {
      "command": "npx",
      "args": ["@sunra/mcp-server"],
      "description": "SUNRA AI model access"
    }
  }
}
```

### Windsurf

对于 Windsurf IDE，在工作区设置中配置 MCP：

```json theme={null}
{
  "mcp": {
    "servers": {
      "sunra-mcp-server": {
        "command": "npx",
        "args": ["@sunra/mcp-server"],
        "timeout": 30000
      }
    }
  }
}
```

### Claude Desktop

添加到您的 Claude Desktop 配置文件：

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json theme={null}
{
  "mcpServers": {
    "sunra-mcp-server": {
      "command": "npx",
      "args": ["@sunra/mcp-server"]
    }
  }
}
```

### 其他兼容MCP的工具

对于任何其他支持 MCP 的工具，请使用此通用配置模式：

```json theme={null}
{
  "mcpServers": {
    "sunra-mcp-server": {
      "command": "npx",
      "args": ["@sunra/mcp-server"],
      "env": {
        "SUNRA_KEY": "${SUNRA_KEY}"
      }
    }
  }
}
```

## 环境设置

### 设置您的API密钥

您可以通过几种方式配置 SUNRA API 密钥：

#### 选项1：环境变量（推荐）

```bash theme={null}
export SUNRA_KEY="your-api-key-here"
```

对于Windows：

```cmd theme={null}
set SUNRA_KEY=your-api-key-here
```

#### 选项2：配置文件

一些编辑器允许您直接在 MCP 配置中设置环境变量：

```json theme={null}
{
  "mcpServers": {
    "sunra-mcp-server": {
      "command": "npx",
      "args": ["@sunra/mcp-server"],
      "env": {
        "SUNRA_KEY": "your-api-key-here"
      }
    }
  }
}
```

#### 选项3：运行时配置

MCP 服务器还支持使用 `set-sunra-key` 工具在运行时设置 API 密钥。

## 可用的MCP工具

配置完成后，您将通过 AI 助手访问这些工具：

### 模型管理

* `list-models` - 浏览所有可用的 AI 模型
* `search-models` - 按关键字查找模型
* `model-schema` - 获取特定模型的输入/输出模式

### 请求管理

* `submit` - 向模型端点提交请求
* `status` - 检查请求状态和日志
* `result` - 检索完成的结果
* `cancel` - 取消运行中的请求
* `subscribe` - 提交并等待完成

### 文件管理

* `upload` - 将文件上传到 SUNRA 存储

## 使用示例

### 列出可用模型

```
使用 list-models 工具向我展示可用的 AI 模型。
```

### 生成图像

```
使用 submit 工具通过 black-forest-labs/flux-1.1-pro/text-to-image 端点生成图像。
使用提示："夕阳下的宁静山景"
```

### 检查请求状态

```
检查请求 ID 的状态：pd_xxxxxx
```

## 故障排除

### 常见问题

**找不到 MCP 服务器**

* 确保 Node.js 已安装且可访问
* 尝试全局安装：`npm install -g @sunra/mcp-server`
* 验证命令路径是否正确

**认证错误**

* 检查您的 SUNRA\_KEY 环境变量是否已设置
* 在 [SUNRA 控制台](https://sunra.ai/dashboard/api-tokens)验证您的 API 密钥是否有效
* 尝试使用 `set-sunra-key` 工具设置密钥

**连接超时**

* 在配置中增加超时值
* 检查您的互联网连接
* 验证 SUNRA API 状态

**权限错误**

* 确保配置文件有适当的文件权限
* 尝试使用适当的用户权限运行

### 获取帮助

如果您遇到问题：

1. 查看 [SUNRA 文档](https://docs.sunra.ai)
2. 查看您编辑器的 MCP 文档
3. 在 [GitHub](https://github.com/sunra-ai/sunra-clients/issues) 上提出问题

## 下一步

配置 MCP 服务器后：

1. **探索模型**：使用 `list-models` 查看所有可用的 AI 功能
2. **尝试示例**：从简单的文本转图像或文本转视频生成开始
3. **构建工作流程**：结合多个模型实现复杂的 AI 管道
4. **监控使用情况**：在 [SUNRA 控制台](https://sunra.ai/dashboard/) 中跟踪您的 API 使用情况

MCP 集成使得将强大的 AI 模型直接整合到您的开发工作流程中变得容易，实现快速原型设计和 AI 驱动功能的无缝集成到您的应用程序中。