Connect Qwen Code to tools via MCP

Qwen Code can connect to external tools and data sources through the Model Context Protocol (MCP) . MCP servers give Qwen Code access to your tools, databases, and APIs.

What you can do with MCP

With MCP servers connected, you can ask Qwen Code to:

• Work with files and repos (read/search/write, depending on the tools you enable)
• Query databases (schema inspection, queries, reporting)
• Integrate internal services (wrap your APIs as MCP tools)
• Automate workflows (repeatable tasks exposed as tools/prompts)

[!tip] If you’re looking for the “one command to get started”, jump to Quick start.

Quick start

Qwen Code loads MCP servers from mcpServers in your settings.json. You can configure servers either:

• By editing settings.json directly
• By using qwen mcp commands (see CLI reference)

Add your first server

1. Add a server (example: remote HTTP MCP server):

qwen mcp add --transport http my-server http://localhost:3000/mcp

2. Verify it shows up:

qwen mcp list

3. Restart Qwen Code in the same project (or start it if it wasn’t running yet), then ask the model to use tools from that server.

Where configuration is stored (scopes)

Most users only need these two scopes:

• Project scope (default): .qwen/settings.json in your project root
• User scope: ~/.qwen/settings.json across all projects on your machine

Write to user scope:

qwen mcp add --scope user --transport http my-server http://localhost:3000/mcp

[!tip] For advanced configuration layers (system defaults/system settings and precedence rules), see Settings.

Configure servers

Choose a transport

[!note] If a server supports both, prefer HTTP over SSE.

Configure via settings.json vs qwen mcp add

Both approaches produce the same mcpServers entries in your settings.json—use whichever you prefer.

Stdio server (local process)

JSON (.qwen/settings.json):

{
  "mcpServers": {
    "pythonTools": {
      "command": "python",
      "args": ["-m", "my_mcp_server", "--port", "8080"],
      "cwd": "./mcp-servers/python",
      "env": {
        "DATABASE_URL": "$DB_CONNECTION_STRING",
        "API_KEY": "${EXTERNAL_API_KEY}"
      },
      "timeout": 15000
    }
  }
}

CLI (writes to project scope by default):

qwen mcp add pythonTools -e DATABASE_URL=$DB_CONNECTION_STRING -e API_KEY=$EXTERNAL_API_KEY \
  --timeout 15000 python -m my_mcp_server --port 8080

HTTP server (remote streamable HTTP)

JSON:

{
  "mcpServers": {
    "httpServerWithAuth": {
      "httpUrl": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer your-api-token"
      },
      "timeout": 5000
    }
  }
}

CLI:

qwen mcp add --transport http httpServerWithAuth http://localhost:3000/mcp \
  --header "Authorization: Bearer your-api-token" --timeout 5000

SSE server (remote Server-Sent Events)

JSON:

{
  "mcpServers": {
    "sseServer": {
      "url": "http://localhost:8080/sse",
      "timeout": 30000
    }
  }
}

CLI:

qwen mcp add --transport sse sseServer http://localhost:8080/sse --timeout 30000

Safety and control

Trust (skip confirmations)

• Server trust (trust: true): bypasses confirmation prompts for that server (use sparingly).

Tool filtering (allow/deny tools per server)

Use includeTools / excludeTools to restrict tools exposed by a server (from Qwen Code’s perspective).

Example: include only a few tools:

{
  "mcpServers": {
    "filteredServer": {
      "command": "python",
      "args": ["-m", "my_mcp_server"],
      "includeTools": ["safe_tool", "file_reader", "data_processor"],
      "timeout": 30000
    }
  }
}

Global allow/deny lists

The mcp object in your settings.json defines global rules for all MCP servers:

• mcp.allowed: allow-list of MCP server names (keys in mcpServers)
• mcp.excluded: deny-list of MCP server names

Example:

{
  "mcp": {
    "allowed": ["my-trusted-server"],
    "excluded": ["experimental-server"]
  }
}

Troubleshooting

• Server shows “Disconnected” in qwen mcp list: verify the URL/command is correct, then increase timeout.
• Stdio server fails to start: use an absolute command path, and double-check cwd/env.
• Environment variables in JSON don’t resolve: ensure they exist in the environment where Qwen Code runs (shell vs GUI app environments can differ).

Reference

settings.json structure

Server-specific configuration (mcpServers)

Add an mcpServers object to your settings.json file:

// ... file contains other config objects
{
  "mcpServers": {
    "serverName": {
      "command": "path/to/server",
      "args": ["--arg1", "value1"],
      "env": {
        "API_KEY": "$MY_API_TOKEN"
      },
      "cwd": "./server-directory",
      "timeout": 30000,
      "trust": false
    }
  }
}

Configuration properties:

Required (one of the following):

Optional:

Manage MCP servers with qwen mcp

You can always configure MCP servers by manually editing settings.json, but the CLI is usually faster.

Adding a server (qwen mcp add)

qwen mcp add [options] <name> <commandOrUrl> [args...]

Listing servers (qwen mcp list)

qwen mcp list

Removing a server (qwen mcp remove)

qwen mcp remove <name>