mimo-free-api-mcp

# MiMo Free API MCP🚀 (V2.5 Series) [English](./README_EN.md) | English > Based on the MiMo official website ([aistudio.xiaomimimo.com](https://aistudio.xiaomimimo.com)) reverse-constructed advanced OpenAI compatible gateway + native MCP plugin integration. Now fully adapted to **MiMo V2.5 Full Modal** series, supporting **Thinking (Reasoning Chain) protocol** and **Omni (Full Modal) interaction**. ## 🏗️ Core Features (V2.5 Features) 1. **V2.5 Full Modal Adaptation**: Deeply integrated with `mimo-v2.5` and `mimo-v2.5-pro` models, supporting complex analysis of native images, videos, and audio. 2. **Thinking Protocol Alignment**: Perfectly supports the official latest Reasoning Chain (Thinking) protocol. Streaming output automatically includes `reasoning_content`, truly restoring the AI thinking process. 3. **Transparent Upgrade Routing**: Maintains compatibility with the V2 era. Requests to `mimo-v2-omni` will automatically route to `mimo-v2.5`, and `mimo-v2-pro` will route to `mimo-v2.5-pro`. 4. **Environmental Token Configuration**: Supports one-click deployment through the `token` environment variable (format: `ph.uid.token`) in `.env`. 5. **Native MCP Server**: Integrates the latest MCP standard. Empowers clients like Claude/Cursor with native **internet search (`search`)** and **visual analysis (`vision`)** capabilities. ## 📊 Model Matrix (Model Matrix) | Model ID | Base Capability | Reasoning Thinking Chain | Core Advantage | | :--- | :--- | :--- | :--- | | `mimo-v2.5` | **Full Modal Flagship** | ✅ Enabled by default | Best solution for visual, audio, and multi-modal understanding | | `mimo-v2.5-pro` | **Enhanced Reasoning** | ✅ Enabled by default | Logical rigor, strongest search, and long-text analysis | | `mimo-v2-flash` | **Ultra-Fast Lightweight** | Optional (activated by suffix) | Millisecond-level response, suitable for simple conversations and translations | | `mimo-v2-omni` | (Compatible ID) | ✅ (routes to 2.5) | Compatible with old V2-Omni clients | | `mimo-v2-pro` | (Compatible ID) | ✅ (routes to 2.5-pro) | Compatible with old V2-Pro clients | > [!TIP] > **Force Enable Thinking**: You can force activate the thinking chain mode for any model by adding the `-thinking` suffix to the model ID (e.g., `mimo-v2-flash-thinking`). > [!WARNING] > **Tool Calling Limitations**: Currently, model-native tool calls (Function Calling) are extremely unstable and **cannot be reliably used in agents (like AutoGPT, LangChain Agent, etc.)**. It is recommended to use it only for conversations, visual analysis, or through MCP plugins in supported clients (like Claude/Cursor). ## 🔑 Credentials Configuration (Credentials) The project supports passing credentials through environment variables or API headers. ### Method A: One-Click .env Deployment (Recommended) Create a `.env` file in the root directory (refer to `.env.example`), and fill in the three-part token scraped from the official website: ```env # Format: ph.uid.token or long string obtained from packet capture token=xxxxxxxx.yyyyyyyy.zzzzzzzz ``` ### Method B: OpenAI Header Passing Directly use the Bearer token in API calls: ```bash Authorization: Bearer YOUR_MIMO_TOKEN ``` ## 📂 Local File Access (Local File Access) If you run in a Docker environment, due to container isolation, the service cannot directly read the host machine's path by default. ### Core Workflow: 1. **Multi-Mode Support**: This project supports **URL**, **Base64 data**, and **local file names**. 2. **Mount Mapping (Local Files)**: If you need to use local files, place them in the host machine's directory and mount them to the container's `/app/media` in `docker-compose.yml`: ```yaml volumes: - /your/host/machine/path:/app/media:ro ``` 3. **Direct Access**: After mounting, you only need to tell the AI the file name (e.g., "Analyze `test.mp4`"), and the system will automatically locate it in the `/app/media` directory. ### 💡 Prompting Guide - **File Name (Most Recommended)**: "Analyze this local video: `demo.mp4`" - **URL Address**: "Analyze this online image: `https://example.com/cat.jpg`" - **Base64**: Directly paste the Base64 data URI to the AI. - **Comparative Analysis**: "Compare `local_image.png` and this web image `https://.../2.jpg`" > **Note**: Ensure the AI can access the `vision` tool through its toolset. This project has informed the AI to support multiple sources in the tool description. ## 🤖 MCP Plugin Integration (Cursor / Claude) The MCP service of this project is integrated under port `8001` and has been fully upgraded to the **2025 Streamable HTTP** standard. ### Client Configuration Example: Add the following configuration to `claude_desktop_config.json`: ```json { "mcpServers": { "mimo": { "url": "http://localhost:8001/mcp", "type": "http", "headers": { "Authorization": "Bearer YOUR_TOKEN" } } } } ``` ### Provided Tools: - **`search(query)`**: AI automatically calls MiMo's internet search. - **`vision(query, image)`**: AI analyzes images, videos, audio, or local resources (supports local absolute paths, Base64, or URLs). ## 🐳 Quick Deployment (Deployment) ```bash # 1. Ensure .env is configured with token # 2. Start the container docker compose up -d --build ``` ## ⚖️ Disclaimer This project is for academic exchange only. Please comply with MiMo's official user agreement.