[Bug for MCP&API]: minimax-coding-plan-mcp fails to start when invoked via uvx with environment variables

[samuelhansen]

Basic Information - Models Used

MiniMax M2.7 and the Coding-Plan-MCP

Basic Information - Scenario Description

When attempting to use minimax-coding-plan-mcp as an MCP server via the uvx command with environment variables (MINIMAX_API_KEY and MINIMAX_API_HOST), the server fails to start with a ValueError: MINIMAX_API_KEY environment variable is required error, even when the environment variable is properly set.

Is this bug known and solvable?

• I have followed the GitHub READMEs for Minimax-MCP and Minimax-MCP-JS.
• I have checked the official Minimax documentation and existing GitHub issues，but found no solution.

Information about environment

Component	Version
OS	Linux (Ubuntu)
Python	3.14.3
uv	0.11.8
minimax-coding-plan-mcp	latest from uvx

Trace-ID in the request head

N/A

Description

Steps to Reproduce

1. Set environment variables:

   export MINIMAX_API_KEY="sk-cp-YOUR_KEY_HERE"
   export MINIMAX_API_HOST="https://api.minimax.io"

2. Run the MCP server via uvx:

   uvx minimax-coding-plan-mcp -y

3. Expected: Server starts and listens for MCP requests
   Actual: Server crashes immediately with ValueError: MINIMAX_API_KEY environment variable is required

---

Attempted Fixes

Approach 1: StdioServerParameters env dict

server_params = StdioServerParameters(
    command="uvx",
    args=["minimax-coding-plan-mcp", "-y"],
    env={"MINIMAX_API_KEY": api_key, "MINIMAX_API_HOST": api_host},
)

Result: Fails with same error.

Approach 2: os.environ before subprocess spawn

os.environ["MINIMAX_API_KEY"] = api_key
os.environ["MINIMAX_API_HOST"] = api_host
server_params = StdioServerParameters(command="uvx", args=["minimax-coding-plan-mcp", "-y"])

Result: Fails - subprocess doesn't inherit modified os.environ.

Approach 3: Inline env in shell command

MINIMAX_API_KEY="sk-cp-..." MINIMAX_API_HOST="https://api.minimax.io" uvx minimax-coding-plan-mcp -y

Result: Fails with ValueError: MINIMAX_API_HOST environment variable is required

Even though MINIMAX_API_HOST is explicitly set inline!

---

Root Cause

In minimax_mcp/server.py (line ~33-35):

if not os.environ.get("MINIMAX_API_KEY"):
    raise ValueError("MINIMAX_API_KEY environment variable is required")

The check uses os.environ.get() evaluated at module import time, not at server startup/runtime. When uvx spawns the server:

1. uvx downloads and extracts the package
2. Python starts executing minimax-coding-plan-mcp as __main__
3. Import of minimax_mcp.server happens
4. At this point, the subprocess may not yet have inherited the environment properly
5. Check fails even though env vars were passed to StdioServerParameters

Note: This is the working hypothesis. A definitive fix would require testing with the actual server code to confirm import timing.

---

Impact

Use Case	Impact
MCP Python SDK programmatic access	❌ Blocked
AI coding applications (Claude Code, Cursor, OpenCode)	❌ Blocked
Direct CLI with env vars	❌ Blocked

Other MCP servers (e.g., open-code, filesystem) work correctly with the same StdioServerParameters pattern. The issue appears specific to how minimax-coding-plan-mcp handles environment variables at import time.

---

Expected Behavior

1. Accept MINIMAX_API_KEY and MINIMAX_API_HOST environment variables
2. Start successfully when provided via standard methods (shell export, env: in StdioServerParameters)
3. Not crash before beginning to accept connections

---

Existing Fix

PR #34 adds CLI argument support (--api-key, --api-host) to work around this issue. This PR is open but not yet merged.

The workaround after PR #34 merges:

{
  "command": "uvx",
  "args": [
    "minimax-coding-plan-mcp",
    "-y",
    "--api-key=your-key",
    "--api-host=https://api.minimax.io"
  ]
}

---

What We Need

1. Merge PR #34 - The fix already exists and addresses this issue
2. Release new version - After merge, publish to uvx so users can update
3. Documentation - Update README to show CLI arg usage as primary method

---

Test Script

import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def test_mcp():
    params = StdioServerParameters(
        command="uvx",
        args=["minimax-coding-plan-mcp", "-y"],
        env={
            "MINIMAX_API_KEY": "YOUR_KEY_HERE",
            "MINIMAX_API_HOST": "https://api.minimax.io",
        },
    )

    async with stdio_client(params) as (stdio, write):
        session = ClientSession(stdio, write)
        await session.initialize()
        result = await session.list_tools()
        print(f"Connected! Tools: {[t.name for t in result.tools]}")

asyncio.run(test_mcp())

---

Additional Context

• This affects sn2md's ability to use MiniMax's vision model for OCR/image conversion
• sn2md has implemented MCP client code (sn2md/mcp_vision.py) that is waiting on this fix
• Related: sn2md issue with MiniMax not supporting Anthropic-style image blocks (type="image")

---

Security Note

This is a bug report for a server startup issue, not a security vulnerability. The server fails to start rather than exposing data improperly. If there are security concerns related to this bug, please disclose responsibly.