Skip to main content
Common issues and solutions when using QWED-MCP.

​
Installation issues

​
”qwed-mcp: command not found”

Cause: Package not in PATH Solutions:
  1. Install globally: 
    pip install qwed-mcp
  2. Check installation: 
    pip show qwed-mcp
python -m qwed_mcp.server
  3. Use full path in config: 
    {
  "mcpServers": {
    "qwed-verification": {
      "command": "python",
      "args": ["-m", "qwed_mcp.server"]
    }
  }
}

​
“ModuleNotFoundError: No module named ‘sympy’”

Cause: QWED SDK dependencies not installed Solution: 
pip install qwed-mcp[all]
# or manually:
pip install sympy z3-solver qwed-legal qwed-finance qwed-ucp

​
Claude Desktop issues

​
Server not appearing in Claude

Check:
  1. Config file location:
    • Windows: %APPDATA%\Claude\claude_desktop_config.json
    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  2. Valid JSON: 
    python -c "import json; json.load(open('path/to/config.json'))"
  3. Restart Claude Desktop (completely quit and reopen)

​
“Failed to start MCP server”

Debug steps:
  1. Test manually: 
    qwed-mcp
# Should start without errors
# Press Ctrl+C to exit
  2. Check logs: 
    # Windows
type %APPDATA%\Claude\logs\mcp*.log
# macOS
cat ~/Library/Logs/Claude/mcp*.log
  3. Enable debug logging: 
    {
  "mcpServers": {
    "qwed-verification": {
      "command": "qwed-mcp",
      "env": {
        "QWED_LOG_LEVEL": "DEBUG",
        "QWED_MCP_TRUSTED_CODE_EXECUTION": "true"
      }
    }
  }
}

​
Tool errors

​
”Code execution is disabled”

Cause: The QWED_MCP_TRUSTED_CODE_EXECUTION environment variable is not set. Solution: Set the variable in your MCP config: 
{
  "mcpServers": {
    "qwed-verification": {
      "command": "qwed-mcp",
      "env": {
        "QWED_MCP_TRUSTED_CODE_EXECUTION": "true"
      }
    }
  }
}
Or when running from the command line: 
QWED_MCP_TRUSTED_CODE_EXECUTION=true qwed-mcp

​
“Unknown tool: verify_math” (or other verify_* tools)

Cause: You are running QWED-MCP v0.2.0 or later, which replaced all individual verify_* tools with a single execute_python_code tool. Solution: Tell Claude: “The verify_* tools have been removed. Use execute_python_code to write and run a Python verification script.” See the migration guide for the full tool mapping.

​
”Execution timed out after 30 seconds”

Cause: The Python script exceeded the execution time limit. Solutions:
  1. Increase timeout: 
    QWED_TIMEOUT=60 qwed-mcp
  2. Optimize the script:
    • Break complex computations into smaller steps
    • Avoid infinite loops or very large data processing

​
ModuleNotFoundError in script output

Cause: The QWED SDK package used in the script is not installed. Solution: Install the required package: 
# For legal verification
pip install qwed-legal

# For finance verification
pip install qwed-finance

# For commerce verification
pip install qwed-ucp

# For core engines (math, logic, code, SQL)
pip install qwed-new

​
Migration issues (v0.1.x to v0.2.0)

​
Claude keeps trying to call verify_math

Cause: Claude’s context may still reference old tool names from previous conversations. Solutions:
  1. Start a new conversation
  2. Explicitly tell Claude: “Use execute_python_code instead of verify_math. Write a Python script that imports sympy to verify the calculation.”

​
Scripts fail with import errors

Cause: The QWED SDK packages are not installed alongside qwed-mcp. Solution: 
pip install qwed-mcp[all]
This installs all QWED SDK packages that your scripts can import.

​
Getting help

  1. GitHub Issues: github.com/QWED-AI/qwed-mcp/issues
  2. Documentation: docs.qwedai.com/mcp
  3. MCP Protocol Docs: modelcontextprotocol.io