> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qwedai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# QWED MCP troubleshooting

> Troubleshoot QWED MCP issues including installation problems, configuration errors, tool execution failures, and migration to execute_python_code.

Common issues and solutions when using QWED-MCP.

***

## Installation issues

### "qwed-mcp: command not found"

**Cause:** Package not in PATH

**Solutions:**

1. **Install globally:**
   ```bash theme={null}
   pip install qwed-mcp
   ```
2. **Check installation:**
   ```bash theme={null}
   pip show qwed-mcp
   python -m qwed_mcp.server
   ```
3. **Use full path in config:**
   ```json theme={null}
   {
     "mcpServers": {
       "qwed-verification": {
         "command": "python",
         "args": ["-m", "qwed_mcp.server"]
       }
     }
   }
   ```

***

### "ModuleNotFoundError: No module named 'sympy'"

**Cause:** QWED SDK dependencies not installed

**Solution:**

```bash theme={null}
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:**
   ```bash theme={null}
   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:**
   ```bash theme={null}
   qwed-mcp
   # Should start without errors
   # Press Ctrl+C to exit
   ```
2. **Check logs:**
   ```bash theme={null}
   # Windows
   type %APPDATA%\Claude\logs\mcp*.log
   # macOS
   cat ~/Library/Logs/Claude/mcp*.log
   ```
3. **Enable debug logging:**
   ```json theme={null}
   {
     "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:

```json theme={null}
{
  "mcpServers": {
    "qwed-verification": {
      "command": "qwed-mcp",
      "env": {
        "QWED_MCP_TRUSTED_CODE_EXECUTION": "true"
      }
    }
  }
}
```

Or when running from the command line:

```bash theme={null}
QWED_MCP_TRUSTED_CODE_EXECUTION=true qwed-mcp
```

***

### "BLOCKED: Unknown MCP tool" (or 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. The `RiskBasedExecutionGateway` blocks any tool name not in its policy table with error code `QWED-MCP-RISK-001`.

The full error message looks like:

```text theme={null}
BLOCKED: Unknown MCP tool 'verify_math' is blocked by default. (verification_id=...)
```

**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](/mcp/tools#migrating-from-v01x) for the full tool mapping and [governance error codes](/mcp/tools#governance-error-codes) for the complete list of `QWED-MCP-RISK-*` codes.

***

### "Execution timed out after 30 seconds"

**Cause:** The Python script exceeded the execution time limit.

**Solutions:**

1. **Increase timeout:**
   ```bash theme={null}
   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:

```bash theme={null}
# 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:**

```bash theme={null}
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](https://github.com/QWED-AI/qwed-mcp/issues)
2. **Documentation:** [docs.qwedai.com/mcp](https://docs.qwedai.com/docs/mcp/overview)
3. **MCP Protocol Docs:** [modelcontextprotocol.io](https://modelcontextprotocol.io)