MCP Server Installer

Autonomously add MCP (Model Context Protocol) servers to Claude Code configuration at the user level (~/.claude/mcp.json).

When to Activate

• "add mcp server"
• "install mcp", "configure mcp"
• "new mcp server", "setup mcp"
• "add [server-name] mcp"
• User provides MCP server configuration JSON

Process

Step 1: Gather Server Information

Ask user for:

1. Server name (e.g., "mobile-mcp-server")

   • Must be lowercase with hyphens
   • Will be used as the key in mcpServers object

2. Transport type:

   • stdio - Local command execution (most common)
   • http - Remote HTTP server
   • sse - Server-Sent Events (deprecated but supported)

3. Based on transport type:

   For stdio:

   • Command (e.g., "npx", "node", "/usr/local/bin/server")
   • Arguments array (e.g., ["@daipham/mobile-mcp-server@latest"])
   • Environment variables (if needed)

   For http:

   • URL (e.g., "https://api.example.com/mcp")
   • Headers (optional, e.g., {"Authorization": "Bearer ${API_KEY}"})

   For sse:

   • URL (e.g., "https://api.example.com/sse")
   • Headers (optional)

Step 2: Collect Environment Variables

Always ask user: "Does this MCP server require any environment variables?"

If yes, for each variable:

• Variable name (e.g., "API_KEY", "DATABASE_URL")
• Description/purpose
• Whether it's required or optional
• Default value (if optional)

Document in output: List all required environment variables with instructions on where to set them.

Step 3: Read Existing Configuration

Check for existing .mcp.json at user level:

cat ~/.claude/mcp.json

If file doesn't exist, create new structure. If exists, parse and merge.

Step 4: Generate Configuration

Use templates from templates.md to generate the server configuration based on transport type.

Apply environment variable syntax:

• ${VAR} - Required variable (will error if not set)
• ${VAR:-default} - Optional variable with default value

Step 5: Update Configuration File

Merge strategy:

• Preserve existing servers
• Add new server to mcpServers object
• Maintain JSON formatting (2-space indent)
• Validate JSON before writing

Write to ~/.claude/mcp.json.

Step 6: Create Environment File Reference

If environment variables are needed, inform user:

⚠️ Environment Variables Required:

Set these in your shell profile (~/.zshrc or ~/.bashrc):

export VAR_NAME="value"
export ANOTHER_VAR="value"

Or create a project-specific .env file and reference it:
"envFile": "${workspaceFolder}/.env"

Step 7: Validate and Test

Run validation:

claude mcp list

Show the newly added server in the output.

Output Format

✅ MCP Server Added: [server-name]

📁 Configuration: ~/.claude/mcp.json

🔧 Transport: [stdio/http/sse]
📦 Command: [command with args] (if stdio)
🌐 URL: [url] (if http/sse)

📋 Configuration Added:
```json
{
  "server-name": {
    // configuration here
  }
}

⚠️ Environment Variables Required:

• VAR_NAME: [description]
• ANOTHER_VAR: [description]

💡 Set environment variables:

1. Add to ~/.zshrc or ~/.bashrc: export VAR_NAME="your-value"

2. Or use project .env file: "envFile": "${workspaceFolder}/.env"

✅ Restart Claude Code to activate the new MCP server.

🧪 Test with: claude mcp list

## Error Handling

- **Invalid JSON**: Show parsing error, ask user to verify configuration
- **Duplicate server name**: Ask if user wants to overwrite existing server
- **Missing required fields**: Prompt for missing information
- **File permission errors**: Suggest checking ~/.claude directory permissions

## Important Notes

1. **User-level scope**: Servers added at `~/.claude/mcp.json` are available across all projects
2. **Environment variables**: Always prompt for environment variables - many MCP servers require API keys or configuration
3. **Restart required**: Claude Code must be restarted after adding MCP servers
4. **Validation**: Use `claude mcp list` to verify the server was added successfully
5. **Security**: Never log or display actual environment variable values

## Reference

See `templates.md` for configuration templates for each transport type.