CLI reference
The mcpbolt CLI reads a pasted config, translates it, and writes the result to one or more AI tool config files. It has a single interactive mode (default) and a handful of flags for scripting.
Invocation
npx mcpbolt [flags]Or, if installed globally:
mcpbolt [flags]Flags
| Flag | Description |
|---|---|
--version | Print the installed version and exit. |
--help | Show usage and available flags. |
--dry-run | Parse and preview all changes but do not write any files. Equivalent to answering "No" at the "Write files now?" prompt, but skips the prompt entirely. |
--target <id> | Pre-select one or more targets (comma-separated) instead of showing the interactive picker. Example: --target claude-desktop,cursor-global. |
--non-interactive | Skip all prompts. Requires the config to be piped or passed via stdin. Combines well with --target for scripting. |
--format <fmt> | Force a specific input format instead of auto-detecting. Valid values: claude, vscode, zed, codex, continue, url, npx, docker. |
Environment variables
| Variable | Description |
|---|---|
MCPBOLT_CONFIG_DIR | Override the directory MCPBolt uses for its own internal state (backups index, etc.). Defaults to ~/.mcpbolt. |
MCPBOLT_NO_COLOR | Set to any non-empty value to disable ANSI colors in output. Useful for CI logs or terminals that don't support color. |
Scripting. For non-interactive use, pipe your config via stdin and combine flags:
cat config.json | mcpbolt --non-interactive --target claude-desktop. MCPBolt exits with code 0 on success, non-zero on error.Writer targets
These are the id values you pass to --target. MCPBolt auto-detects which are installed on your machine during interactive mode.
| ID | App | Scope | Config file |
|---|---|---|---|
claude-desktop | Claude Desktop | user | ~/Library/Application Support/Claude/claude_desktop_config.json |
claude-code-global | Claude Code | user | ~/.claude.json |
claude-code-project | Claude Code | project | .mcp.json |
cursor-global | Cursor | user | ~/.cursor/mcp.json |
cursor-project | Cursor | project | .cursor/mcp.json |
vscode-global | VS Code | user | ~/Library/Application Support/Code/User/mcp.json |
vscode-project | VS Code | project | .vscode/mcp.json |
codex-global | Codex CLI | user | ~/.codex/config.toml |
codex-project | Codex CLI | project | .codex/config.toml |
windsurf | Windsurf | user | ~/.codeium/windsurf/mcp_config.json |
zed-global | Zed | user | ~/.config/zed/settings.json |
zed-project | Zed | project | .zed/settings.json |
continue | Continue | user | ~/.continue/config.yaml |
gemini-global | Gemini CLI | user | ~/.gemini/settings.json |
gemini-project | Gemini CLI | project | .gemini/settings.json |
roo | Roo Code | project | .roo/mcp.json |
Merge, not overwrite. MCPBolt always merges the target server key into the existing config file. Every other key in the file is left untouched. If the file does not exist, it is created with only the new server entry.