Qualty MCP User Setup

This guide shows how to install and use the published qualty-mcp package from PyPI in a new project, for both Claude Code and Cursor.

Prerequisites

• Python 3.11+ available on your machine
• pipx installed
• A Qualty API token (qlty_ci_...)

Install pipx if needed:

python3 -m pip install --user --upgrade pipx
python3 -m pipx ensurepath

Open a new terminal after ensurepath.

1) Install Qualty MCP

pipx install qualty-mcp

If already installed and you want latest:

pipx upgrade qualty-mcp

2) Go to your project folder

cd /path/to/your-project

All project-specific files (.mcp.json, .qualty.json) will be created in the current folder.

3) Initialize token + default project

qualty-mcp init

This will:

• prompt for your qlty_ci_... token
• fetch projects in your account
• let you pick an active project for this workspace

Notes:

• token is stored globally at ~/.qualty/credentials
• active project is stored per project in .qualty.json

4A) Configure MCP for Claude Code

qualty-mcp install-claude-code

4B) Configure MCP for Cursor

qualty-mcp install-cursor

5) Restart your client

After writing .mcp.json, fully restart:

• Claude Code, or
• Cursor

This reloads MCP servers and starts qualty-mcp serve.

6) Verify setup

From the same project directory:

qualty-mcp doctor
qualty-mcp status

Expected:

• token configured
• API reachable
• default project configured

Common commands

List/switch active project for this workspace

qualty-mcp list-projects

or directly:

qualty-mcp switch-project --project-id 123
qualty-mcp switch-project --project-name "My Project"

Show config snippet only

qualty-mcp print-claude-code-config
qualty-mcp print-cursor-config

File model (important)

• ~/.qualty/credentials
  Global token for this OS user (shared across folders)

• .qualty.json
  Per-project active project defaults

• .mcp.json
  Per-project MCP launch config for Claude Code/Cursor

Troubleshooting

Could not fetch projects: [Errno 8] nodename nor servname provided

This usually means local/network DNS issues or restricted network environment.

First verify package defaults:

qualty-mcp doctor
qualty-mcp status

Then restart client.

MCP changes not reflected

• Confirm you are in the right project folder
• Re-run install command for that project
• Restart Claude Code/Cursor

Reconfigure token

rm -f ~/.qualty/credentials
qualty-mcp init

Quickstart (copy/paste)

pipx install qualty-mcp
cd /path/to/your-project
qualty-mcp init
qualty-mcp install-claude-code
qualty-mcp doctor

Use install-cursor instead of install-claude-code if needed.