# MiniMax MCP Server

> 让 AI Agent 通过 Model Context Protocol (MCP) 调用 MiniMax AI 能力

## 功能概述

`mcp-minimax-server` 将 MiniMax AI API 桥接到 MCP 协议，使 AI Agent（如 OpenClaw）能够通过标准化的 MCP 工具接口调用 MiniMax 的核心 AI 能力：

| 工具 | 说明 |
|------|------|
| `minimax_text_understand` | 图片理解（OCR、图表分析、视觉问答） |
| `minimax_image_generation` | 文字生成图片 |
| `minimax_speech_synthesis` | 文本转语音 |

## 架构设计

```
AI Agent (OpenClaw)
    │
    │  MCP Protocol (JSON-RPC over stdio)
    ▼
┌─────────────────────────┐
│  mcp-minimax-server     │
│  ┌───────────────────┐   │
│  │  MCP SDK Server   │   │
│  └────────┬──────────┘   │
│           │              │
│  ┌────────▼──────────┐   │
│  │  Tool Handlers    │   │
│  │  ├─ text_understand│  │
│  │  ├─ image_generation│ │
│  │  └─ speech_synthesis│ │
│  └────────┬──────────┘   │
└───────────┼──────────────┘
            │ REST API
            ▼
      MiniMax API
```

## 安装

```bash
# 克隆或下载
git clone https://github.com/YOUR_USERNAME/mcp-minimax-server.git
cd mcp-minimax-server

# 安装依赖
npm install

# 编译 TypeScript
npm run build
```

## 配置

需要设置两个环境变量：

```bash
export MINIMAX_API_KEY="your_api_key_here"
export MINIMAX_GROUP_ID="your_group_id_here"
```

获取方式：
1. 访问 [MiniMax 开放平台](https://platform.minimaxi.com/)
2. 创建应用获取 API Key 和 Group ID

## 使用方式

### 独立运行

```bash
npm start
```

### 集成到 OpenClaw

在 OpenClaw 配置中添加 MCP 服务器：

```json
{
  "mcpServers": {
    "minimax": {
      "command": "node",
      "args": ["/path/to/mcp-minimax-server/dist/index.js"],
      "env": {
        "MINIMAX_API_KEY": "your_key",
        "MINIMAX_GROUP_ID": "your_group"
      }
    }
  }
}
```

### Claude Desktop 集成

```json
{
  "mcpServers": {
    "minimax": {
      "command": "node",
      "args": ["/path/to/mcp-minimax-server/dist/index.js"],
      "env": {
        "MINIMAX_API_KEY": "your_key",
        "MINIMAX_GROUP_ID": "your_group"
      }
    }
  }
}
```

## 工具详解

### minimax_text_understand

分析图片内容，支持 OCR、图表解读、视觉问答等。

```javascript
// MCP 调用示例
{
  name: "minimax_text_understand",
  arguments: {
    image_url: "https://example.com/image.png",
    prompt: "提取图片中的所有文字"
  }
}
```

### minimax_image_generation

根据文字描述生成图片。

```javascript
// MCP 调用示例
{
  name: "minimax_image_generation",
  arguments: {
    prompt: "一只可爱的橘猫在阳光下打盹，写实风格",
    model: "MiniMax-Image-01"
  }
}
```

### minimax_speech_synthesis

将文本转换为自然语音。

```javascript
// MCP 调用示例
{
  name: "minimax_speech_synthesis",
  arguments: {
    text: "欢迎使用 MiniMax 语音合成服务",
    voice_id: "male-qn-qingse",
    speed: 1.0,
    pitch: 0
  }
}
```

支持的声音ID：
- `male-qn-qingse` - 男声-青年
- `female-tianmei` - 女声-甜美
- `male-qn-ningxuan` - 男声-低沉

## 技术栈

- **运行时**: Node.js 22+
- **语言**: TypeScript (ESNext)
- **MCP SDK**: `@modelcontextprotocol/sdk ^1.0.0`
- **协议**: MCP over stdio (JSON-RPC)

## 项目结构

```
mcp-minimax-server/
├── src/
│   └── index.ts          # MCP 服务器主入口
├── dist/                  # 编译输出
├── package.json
├── tsconfig.json
└── README.md
```

## 开发

```bash
# 调试运行
npm run dev

# 编译
npm run build

# 类型检查
npx tsc --noEmit
```

## License

MIT