Integrating QuickMCP with Claude Desktop: Step-by-Step

Claude Desktop's MCP support lets you extend Claude with custom tools. Here's how to integrate QuickMCP servers seamlessly.

Prerequisites

Before starting:

• QuickMCP CLI installed (dotnet tool install -g QuickMCP.CLI)
• Claude Desktop installed
• API specification (OpenAPI or Swagger)
• API credentials (if required)

Finding the Configuration File

Claude Desktop stores MCP server configurations in a JSON file.

macOS

~/Library/Application Support/Claude/claude_desktop_config.json

Windows

%APPDATA%\Claude\claude_desktop_config.json

Linux

~/.config/Claude/claude_desktop_config.json

Basic Integration

Step 1: Create QuickMCP Configuration

quickmcp build config \
  --spec-url https://api.example.com/swagger.json \
  --auth bearertoken \
  --output-path ./my-api-config.json

Step 2: Edit Configuration

Add your credentials using environment variables:

{
  "serverId": "my-api",
  "specificationUrl": "https://api.example.com/swagger.json",
  "authentication": {
    "type": "Bearer",
    "token": "${MY_API_TOKEN}"
  }
}

Step 3: Add to Claude Desktop

Open claude_desktop_config.json and add:

{
  "mcpServers": {
    "my-api": {
      "command": "quickmcp",
      "args": [
        "serve",
        "--config-path",
        "/full/path/to/my-api-config.json"
      ],
      "env": {
        "MY_API_TOKEN": "your-actual-token-here"
      }
    }
  }
}

Step 4: Restart Claude Desktop

Close and reopen Claude Desktop. Your tools should now appear.

Real Example: GitHub API

Generate Config

quickmcp build config \
  --spec-url https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json \
  --auth bearertoken \
  --output-path ~/quickmcp/github-config.json

Claude Desktop Config

{
  "mcpServers": {
    "github": {
      "command": "quickmcp",
      "args": [
        "serve",
        "--config-path",
        "/Users/yourname/quickmcp/github-config.json"
      ],
      "env": {
        "GITHUB_TOKEN": "ghp_your_personal_access_token"
      }
    }
  }
}

Now Claude can:

• Create and manage issues
• Search repositories
• Read file contents
• Manage pull requests

Multiple API Integration

Example: GitHub + Stripe + Internal API

{
  "mcpServers": {
    "github": {
      "command": "quickmcp",
      "args": ["serve", "--config-path", "/path/to/github-config.json"],
      "env": {
        "GITHUB_TOKEN": "ghp_token"
      }
    },
    "stripe": {
      "command": "quickmcp",
      "args": ["serve", "--config-path", "/path/to/stripe-config.json"],
      "env": {
        "STRIPE_API_KEY": "sk_live_token"
      }
    },
    "internal": {
      "command": "quickmcp",
      "args": ["serve", "--config-path", "/path/to/internal-config.json"],
      "env": {
        "INTERNAL_API_KEY": "your-key"
      }
    }
  }
}

Claude now has access to all three APIs simultaneously.

Advanced Configuration

With Path Filtering

First, create a filtered config:

quickmcp build config \
  --spec-url https://api.company.com/swagger.json \
  --auth oauth \
  --exclude-paths "/admin/*,/internal/*" \
  --output-path ./company-api-config.json

Then add to Claude Desktop:

{
  "mcpServers": {
    "company-api": {
      "command": "quickmcp",
      "args": ["serve", "--config-path", "/path/to/company-api-config.json"],
      "env": {
        "OAUTH_CLIENT_ID": "your-client-id",
        "OAUTH_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

With Logging Enabled

Add the --logging flag for debugging:

{
  "mcpServers": {
    "my-api": {
      "command": "quickmcp",
      "args": [
        "serve",
        "--config-path",
        "/path/to/config.json",
        "--logging"
      ],
      "env": {
        "API_TOKEN": "your-token"
      }
    }
  }
}

Troubleshooting

Issue: Server Not Appearing

Check:

1. QuickMCP installed globally: quickmcp --version
2. Config path is absolute, not relative
3. Environment variables are set
4. Claude Desktop was restarted

Test manually:

quickmcp serve --config-path /path/to/config.json --logging

Issue: Authentication Failures

Solution:

Enable logging and check credentials:

{
  "mcpServers": {
    "my-api": {
      "command": "quickmcp",
      "args": ["serve", "--config-path", "/path/to/config.json", "--logging"]
    }
  }
}

Restart Claude Desktop and watch the logs.

Issue: Wrong Tools Showing

Cause: Spec includes endpoints you don't want.

Solution: Rebuild config with path filtering:

quickmcp build config \
  --spec-url https://api.example.com/swagger.json \
  --exclude-paths "/unwanted/*" \
  --output-path ./filtered-config.json

Update Claude Desktop config to use the new file.

Issue: Environment Variables Not Working

Cause: Variable names in config don't match environment section.

Fix: Ensure consistency:

Config file:

{
  "authentication": {
    "token": "${API_TOKEN}"
  }
}

Claude Desktop config:

{
  "env": {
    "API_TOKEN": "actual-token"
  }
}

Testing Your Integration

Step 1: Start Claude Desktop

Look for the MCP indicator showing your servers are connected.

Step 2: Test a Simple Query

Ask Claude something that requires your API:

"Can you list my GitHub repositories?"

Step 3: Verify Tool Usage

Claude should:

1. Recognize the available tools
2. Call the appropriate API endpoint
3. Return formatted results

Managing Multiple Environments

Dev Environment

{
  "mcpServers": {
    "api-dev": {
      "command": "quickmcp",
      "args": ["serve", "--config-path", "/path/to/dev-config.json"],
      "env": {
        "API_KEY": "dev-key"
      }
    }
  }
}

Production Environment

{
  "mcpServers": {
    "api-prod": {
      "command": "quickmcp",
      "args": ["serve", "--config-path", "/path/to/prod-config.json"],
      "env": {
        "API_KEY": "prod-key"
      }
    }
  }
}

Switch by commenting out the one you don't want to use.

Best Practices

1. Use Descriptive Server Names

// Good
"github-personal": {...}
"github-work": {...}
"stripe-live": {...}

// Bad
"server1": {...}
"api": {...}

2. Keep Configs Organized

Create a dedicated directory:

mkdir ~/quickmcp-configs
cd ~/quickmcp-configs

Store all configs there:

~/quickmcp-configs/
  github-config.json
  stripe-config.json
  internal-api-config.json

3. Document Your Setup

Create a README:

# My QuickMCP Servers

## GitHub
- Config: ~/quickmcp-configs/github-config.json
- Token: Personal access token with repo scope
- Endpoints: Issues, PRs, repositories

## Stripe
- Config: ~/quickmcp-configs/stripe-config.json
- Key: Live API key (restricted)
- Endpoints: Customers, payments (read-only)

4. Version Control (Safely)

Store configs in Git, but use environment variables:

git add github-config.json
git add stripe-config.json

# Never commit:
# - Actual tokens
# - API keys
# - Passwords

Performance Tips

Tip 1: Filter Unnecessary Endpoints

More endpoints = slower tool discovery. Filter aggressively:

quickmcp build config \
  --only-for-paths "/users/*,/repos/*" \
  --output-path ./minimal-config.json

Tip 2: Use AI Metadata

Helps Claude understand tools faster:

quickmcp build config \
  --ai-metadata \
  --output-path ./config.json

Tip 3: Restart Sparingly

Claude Desktop only loads MCP servers on startup. Make all config changes at once, then restart.

Security Considerations

Never Store Secrets in Config

❌ Don't:

{
  "env": {
    "API_KEY": "actual-secret-key-abc123"
  }
}

✅ Do:
Use system environment variables or secure credential managers.

Limit Scopes

When using OAuth, request minimum scopes:

{
  "authentication": {
    "type": "OAuth2",
    "scopes": ["read"]  // Not ["read", "write", "admin"]
  }
}

Next Steps

• Learn Path Filtering for security
• Explore Authentication Methods
• Master CLI Commands

Integrating QuickMCP with Claude Desktop unlocks powerful API access for your AI assistant. Start simple, test thoroughly, and expand from there.