User Configuration MCP

Manage MCP (Model Context Protocol) server configurations stored in ~/.claude.json.

Arguments

Argument	Description
--list	List all configured MCP servers with details
--export FILE	Export MCP configs to JSON file (for sharing)
--import FILE	Import MCP configs from JSON file
--add NAME	Add a new MCP server interactively
--remove NAME	Remove an MCP server (with confirmation)
(no args)	Show MCP server summary

MCP Server Location

User-scope MCP servers are stored in ~/.claude.json under the mcpServers field:

{
  "mcpServers": {
    "perplexity": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic/perplexity-mcp"]
    }
  }
}

Note: There is NO ~/.mcp.json file. User-scope MCP servers go in ~/.claude.json.

Workflow

Mode: List (--list or no args)

List all MCP servers with details:

import json
from pathlib import Path

claude_json = Path.home() / ".claude.json"

if not claude_json.exists():
    print("No global configuration found (~/.claude.json)")
    print("No MCP servers configured at user level")
    exit(0)

config = json.load(open(claude_json))
servers = config.get("mcpServers", {})

if not servers:
    print("No MCP servers configured")
    exit(0)

print(f"# MCP Servers ({len(servers)} configured)\n")

for name, server in servers.items():
    server_type = server.get("type", "unknown")
    command = server.get("command", "N/A")
    args = server.get("args", [])

    print(f"## {name}")
    print(f"  Type: {server_type}")
    print(f"  Command: {command}")
    if args:
        print(f"  Args: {' '.join(args)}")
    if "env" in server:
        env_keys = list(server["env"].keys())
        print(f"  Env vars: {', '.join(env_keys)}")
    print()

Mode: Export (--export FILE)

Export MCP configurations to a shareable JSON file:

import json
from pathlib import Path
from datetime import datetime, timezone

claude_json = Path.home() / ".claude.json"
export_path = Path("mcp-servers-export.json")  # From argument

config = json.load(open(claude_json))
servers = config.get("mcpServers", {})

# Sanitize: Remove env vars with sensitive values
sanitized = {}
for name, server in servers.items():
    server_copy = server.copy()
    if "env" in server_copy:
        # Keep env var names but redact values that look sensitive
        sanitized_env = {}
        for key, value in server_copy["env"].items():
            if any(s in key.upper() for s in ["KEY", "TOKEN", "SECRET", "PASSWORD"]):
                sanitized_env[key] = "[REDACTED - set your own value]"
            else:
                sanitized_env[key] = value
        server_copy["env"] = sanitized_env
    sanitized[name] = server_copy

export_data = {
    "exported_at": datetime.now(timezone.utc).isoformat(),
    "note": "Exported MCP server configurations. Review and update any [REDACTED] values.",
    "mcpServers": sanitized
}

json.dump(export_data, open(export_path, "w"), indent=2)
print(f"✅ Exported {len(sanitized)} MCP server(s) to {export_path}")
print("⚠️ Review file for [REDACTED] values that need to be set")

Mode: Import (--import FILE)

Import MCP configurations from a JSON file:

import json
from pathlib import Path

claude_json = Path.home() / ".claude.json"
import_path = Path("mcp-servers-export.json")  # From argument

if not import_path.exists():
    print(f"❌ Import file not found: {import_path}")
    exit(1)

import_data = json.load(open(import_path))
new_servers = import_data.get("mcpServers", {})

if not new_servers:
    print("❌ No MCP servers found in import file")
    exit(1)

# Load existing config
if claude_json.exists():
    config = json.load(open(claude_json))
else:
    config = {}

existing = config.get("mcpServers", {})

# Show what will be imported
print(f"Importing {len(new_servers)} MCP server(s):")
for name in new_servers:
    status = "UPDATE" if name in existing else "NEW"
    print(f"  • {name} [{status}]")

# Check for [REDACTED] values
for name, server in new_servers.items():
    for key, value in server.get("env", {}).items():
        if "[REDACTED" in str(value):
            print(f"⚠️ {name} has redacted env var: {key}")
            print("   You'll need to set this value manually")

# Use AskUserQuestion for confirmation
# If confirmed:
config["mcpServers"] = {**existing, **new_servers}
json.dump(config, open(claude_json, "w"), indent=2)
print(f"✅ Imported {len(new_servers)} MCP server(s)")
print("⚠️ Restart Claude Code to activate new servers")

Mode: Add (--add NAME)

Add a new MCP server interactively:

import json
from pathlib import Path

claude_json = Path.home() / ".claude.json"
server_name = "my-new-server"  # From argument

# Load existing config
if claude_json.exists():
    config = json.load(open(claude_json))
else:
    config = {}

if server_name in config.get("mcpServers", {}):
    print(f"⚠️ Server '{server_name}' already exists")
    # Use AskUserQuestion: Overwrite or cancel?

# Use AskUserQuestion to gather:
# 1. Server type (stdio, sse, etc.)
# 2. Command (e.g., npx, python, etc.)
# 3. Args (e.g., -y @package/name)
# 4. Any environment variables

# Example result:
new_server = {
    "type": "stdio",
    "command": "npx",
    "args": ["-y", "@example/mcp-server"]
}

if "mcpServers" not in config:
    config["mcpServers"] = {}

config["mcpServers"][server_name] = new_server
json.dump(config, open(claude_json, "w"), indent=2)

print(f"✅ Added MCP server: {server_name}")
print("⚠️ Restart Claude Code to activate")

Mode: Remove (--remove NAME)

Remove an MCP server:

import json
from pathlib import Path

claude_json = Path.home() / ".claude.json"
server_name = "server-to-remove"  # From argument

config = json.load(open(claude_json))
servers = config.get("mcpServers", {})

if server_name not in servers:
    print(f"❌ Server not found: {server_name}")
    print(f"Available servers: {', '.join(servers.keys())}")
    exit(1)

# Use AskUserQuestion for confirmation
# If confirmed:
del config["mcpServers"][server_name]
json.dump(config, open(claude_json, "w"), indent=2)

print(f"✅ Removed MCP server: {server_name}")
print("⚠️ Restart Claude Code to apply changes")

Output Format

Server List

# MCP Servers (5 configured)

| Name | Type | Package/Command |
|------|------|-----------------|
| perplexity | stdio | @anthropic/perplexity-mcp |
| microsoft-learn | stdio | @anthropic/microsoft-learn-mcp |
| firecrawl | stdio | @anthropic/firecrawl-mcp |
| context7 | stdio | @anthropic/context7-mcp |
| ref | stdio | @anthropic/ref-mcp |

## Quick Actions

- Export configs: `/user-config:mcp --export mcp-backup.json`
- Add server: `/user-config:mcp --add new-server`
- Remove server: `/user-config:mcp --remove old-server`

Common MCP Servers

These are commonly used MCP servers:

Package	Purpose
@anthropic/perplexity-mcp	AI-powered web search
@anthropic/microsoft-learn-mcp	Microsoft documentation
@anthropic/firecrawl-mcp	Web scraping and crawling
@anthropic/context7-mcp	Library documentation
@anthropic/ref-mcp	Reference documentation

Sharing MCP Configurations

To share your MCP setup with a team:

1. Export: /user-config:mcp --export team-mcp.json
2. Review and update any [REDACTED] API keys
3. Share file with team
4. Team imports: /user-config:mcp --import team-mcp.json
5. Each team member sets their own API keys

Related Commands

• /user-config:global - Full global config management
• /user-config:backup - Backup all config including MCP
• /user-config:reset - Reset with MCP preservation
• /mcp - Built-in MCP server status command

Related Skill

This command uses the user-config-management skill for:

• MCP configuration structure
• Known MCP server patterns
• Cross-platform path handling