---
slug: "jayjanii-pi-minimax-mcp"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/jayjanii/pi-minimax-mcp@main/README.md"
repo: "https://github.com/jayjanii/pi-minimax-mcp"
source_file: "README.md"
branch: "main"
---
# pi-minimax-mcp

Web search and image understanding for [Pi](https://github.com/mariozechner/pi) via MiniMax MCP.

## Quick Start

**1. Get a MiniMax API key** at [platform.minimax.io/subscribe/coding-plan](https://platform.minimax.io/subscribe/coding-plan)

**2. Install uvx** (required to run the MiniMax MCP server):

<details open>
<summary>macOS / Linux</summary>

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
</details>

<details>
<summary>Windows (PowerShell)</summary>

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```
</details>

**3. Install the extension:**

```bash
pi install npm:@jayjanii/pi-minimax-mcp
```

**4. Set your API key:**

<details open>
<summary>macOS / Linux</summary>

```bash
export MINIMAX_API_KEY="your-api-key"
```

To persist across sessions, add to `~/.zshrc` or `~/.bashrc`.
</details>

<details>
<summary>Windows (PowerShell)</summary>

```powershell
$env:MINIMAX_API_KEY = "your-api-key"
```

To persist, add to your PowerShell profile or set via System > Environment Variables.
</details>

That's it. Start Pi and the `web_search` and `understand_image` tools are available automatically.

## Usage in Pi

```
Search for the latest TypeScript release notes
```

```
🖼️ understand ./error.png
```

Dropping an image path (`.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`) into the prompt attaches it automatically.

## CLI

```bash
# Web search
pi-minimax-mcp search "quantum computing breakthroughs"
pi-minimax-mcp search "Rust async patterns" --num-results 10 --recency-days 30

# Image analysis
pi-minimax-mcp understand ./diagram.png
pi-minimax-mcp understand ./chart.png --prompt "What trends does this show?"

# Utilities
pi-minimax-mcp config   # show active config (API key redacted)
pi-minimax-mcp init     # create default config file
pi-minimax-mcp tools    # list tools from the MiniMax MCP server
```

## Configuration

Priority order: **CLI flags > env vars > config file > defaults**

### Environment variables

| Variable | Required | Default |
|----------|----------|---------|
| `MINIMAX_API_KEY` | Yes | — |
| `MINIMAX_API_HOST` | No | `https://api.minimax.io` |
| `MINIMAX_MCP_BASE_PATH` | No | — |
| `MINIMAX_API_RESOURCE_MODE` | No | `url` |
| `MINIMAX_MCP_UV_PATH` | No | `uvx` |
| `MINIMAX_MCP_TIMEOUT_MS` | No | `60000` |
| `MINIMAX_MCP_MAX_BYTES` | No | `51200` |
| `MINIMAX_MCP_MAX_LINES` | No | `2000` |

### Config file

<details open>
<summary>macOS / Linux</summary>

Global: `~/.pi/agent/extensions/minimax-mcp.json`  
Project: `.pi/extensions/minimax-mcp.json`
</details>

<details>
<summary>Windows</summary>

Global: `%USERPROFILE%\.pi\agent\extensions\minimax-mcp.json`  
Project: `.pi\extensions\minimax-mcp.json`
</details>

```json
{
  "apiKey": "your-api-key",
  "apiHost": "https://api.minimax.io",
  "resourceMode": "url",
  "timeoutMs": 60000,
  "maxBytes": 51200,
  "maxLines": 2000
}
```

Run `pi-minimax-mcp init` to create this file automatically.

### Pi flags

```bash
pi --minimax-api-key=<key> --minimax-api-host=<host> --minimax-mcp-config=<path>
```

## Troubleshooting

**`uvx: command not found`**

<details open>
<summary>macOS / Linux</summary>

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
# Restart your shell, then verify:
which uvx
```
</details>

<details>
<summary>Windows (PowerShell)</summary>

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
# Open a new terminal, then verify:
where.exe uvx
```
</details>

If uvx is installed but not on PATH, point directly to it:

<details open>
<summary>macOS / Linux</summary>

```bash
export MINIMAX_MCP_UV_PATH="$HOME/.local/bin/uvx"
```
</details>

<details>
<summary>Windows (PowerShell)</summary>

```powershell
$env:MINIMAX_MCP_UV_PATH = "$env:USERPROFILE\.local\bin\uvx.exe"
```
</details>

**`MiniMax API key is required`**
```bash
# Or run: pi-minimax-mcp init  (then edit the generated file)
export MINIMAX_API_KEY="your-key"   # macOS / Linux
```
```powershell
$env:MINIMAX_API_KEY = "your-key"   # Windows
```

## Programmatic usage

```typescript
import { MiniMaxMcpClient } from "@jayjanii/pi-minimax-mcp";

const client = new MiniMaxMcpClient({ apiKey: process.env.MINIMAX_API_KEY! });

const search = await client.webSearch({ query: "TypeScript 5.5 features", numResults: 5 });
const image  = await client.understandImage({ imagePath: "./diagram.png", prompt: "Explain this" });

client.disconnect();
```

## License

MIT