@mcp/claude-code-config

A Model Context Protocol (MCP) server that allows Claude Code to manage its own configuration files with atomic writes, validation, and comprehensive error handling.

Features

• ✅ Atomic Writes: Safe config file modifications with automatic backups
• ✅ Dual Config Support: Manages both CLI (~/.claude.json) and app (~/.config/claude-code/config.json) configs
• ✅ Sync Tools: Keep CLI and app configs in sync
• ✅ Validation: JSON schema validation for keybindings and settings
• ✅ Security: Path traversal protection and permission validation
• ✅ Cross-Platform: Works on Windows, macOS, and Linux
• ✅ Error Handling: Categorized errors with retry logic for transient failures
• ✅ TypeScript: Full type safety with TypeScript
• ✅ Bun Runtime: Optimized for Bun (14x faster than Node.js)

Installation

cd /Users/ebowwa/Desktop/codespaces/MCP/packages/claude-code-config
bun install

Building

bun run build

Usage

Add to Claude Code MCP Configuration

Add to your ~/.claude.json or project .mcp.json:

{
  "mcpServers": {
    "claude-code-config": {
      "command": "bun",
      "args": [
        "/Users/ebowwa/Desktop/codespaces/MCP/packages/claude-code-config/src/index.ts"
      ]
    }
  }
}

Available Tools

CLAUDE.md Management

| Tool | Description | |------|-------------| | read_global_claude_md | Read global CLAUDE.md (~/.claude/CLAUDE.md) | | write_global_claude_md | Write to global CLAUDE.md with backup | | read_project_claude_md | Read project-local CLAUDE.md (.claude/CLAUDE.md) | | write_project_claude_md | Write to project-local CLAUDE.md with backup |

Keybindings Management

| Tool | Description | |------|-------------| | read_keybindings | Read keybindings.json | | write_keybindings | Write to keybindings.json with validation | | add_keybinding | Add or update a single keybinding | | remove_keybinding | Remove a keybinding by key combination |

Settings Management

| Tool | Description | |------|-------------| | read_settings | Read settings.json | | write_settings | Write to settings.json with backup |

Hooks Management

| Tool | Description | |------|-------------| | list_hooks | List all configured hooks | | read_hook | Read a specific hook file | | write_hook | Write or update a hook file |

Utilities

| Tool | Description | |------|-------------| | list_config_files | List all Claude Code config files with metadata | | get_config_path | Get the path to a specific config file | | backup_config | Create a backup of a config file |

MCP Server Management

All MCP management tools support a target parameter to specify which config(s) to operate on:

• 'cli' - CLI config only (~/.claude.json)
• 'app' - App config only (~/.config/claude-code/config.json)
• 'both' - Both configs (default)

| Tool | Description | |------|-------------| | mcp_list | List all configured MCP servers from both CLI and app configs | | mcp_get | Get details about a specific MCP server | | mcp_add | Add a new MCP server configuration to config(s) | | mcp_install | Download and configure an MCP server from npm, GitHub, or local path | | mcp_remove | Remove an MCP server configuration | | mcp_update | Update an existing MCP server configuration | | mcp_sync | Synchronize MCP servers between CLI and app configs |

Examples

Read Global CLAUDE.md

const result = await client.callTool({
  name: 'read_global_claude_md',
  arguments: {},
});

Write Global CLAUDE.md

const result = await client.callTool({
  name: 'write_global_claude_md',
  arguments: {
    content: '# My Instructions\n\nAlways use TypeScript.',
    createBackup: true,
  },
});

Add a Keybinding

const result = await client.callTool({
  name: 'add_keybinding',
  arguments: {
    key: 'ctrl+s',
    command: 'commit',
  },
});

List All Config Files

const result = await client.callTool({
  name: 'list_config_files',
  arguments: {
    includeProject: true,
  },
});

List MCP Servers (Both CLI and App)

const result = await client.callTool({
  name: 'mcp_list',
  arguments: {
    target: 'both',  // 'cli', 'app', or 'both' (default)
    includeHealth: true,
  },
});

Add MCP Server to Both Configs

const result = await client.callTool({
  name: 'mcp_add',
  arguments: {
    name: 'my-mcp',
    command: 'node',
    args: ['/path/to/server.js'],
    target: 'both',  // Adds to both CLI and app configs
  },
});

Sync MCP Configs

// Sync from app config to CLI config
const result = await client.callTool({
  name: 'mcp_sync',
  arguments: {
    source: 'app',  // or 'cli'
    dryRun: false,  // Set true to preview changes
  },
});

Security

• Path validation: All file paths are validated against a whitelist
• No path traversal: .. sequences are blocked
• Permission checks: File permissions are validated before operations
• Atomic writes: Config files are written atomically to prevent corruption
• Automatic backups: Backups are created before modifications

Config File Locations

| File | Location | |------|----------| | Global CLAUDE.md | ~/.claude/CLAUDE.md | | Project CLAUDE.md | .claude/CLAUDE.md | | Keybindings | ~/.claude/keybindings.json | | Settings | ~/.claude/settings.json | | Hooks | ~/.claude/hooks/* | | MCP Servers (CLI) | ~/.claude.json | | MCP Servers (App) | ~/.config/claude-code/config.json |

Error Handling

The server provides detailed error messages with:

• Error category: TRANSIENT, PERMISSION, VALIDATION, SYSTEM, or UNKNOWN
• Retry information: Whether the error is retryable
• User action: Suggested action for the user

Development

# Run in development mode
bun run dev

# Run tests
bun run test

# Build
bun run build

License

MIT