MediaMetz/gemini-cli
1
0
Fork 0
mirror of https://github.com/google-gemini/gemini-cli.git synced 2026-03-10 22:21:22 -07:00
Code Issues Packages Projects Releases Wiki Activity

docs(config): update documentation for settings structure (#7352)

Browse Source
This commit is contained in:
Gal Zahavi
2025-08-28 15:31:33 -07:00
committed by GitHub
parent 10c6af7e49
commit f00cf42f69
12 changed files with 1061 additions and 375 deletions
Download Patch File Download Diff File Expand all files Collapse all files

35
docs/tools/mcp-server.md
View File

@@ -51,7 +51,30 @@ The Gemini CLI uses the `mcpServers` configuration in your `settings.json` file
### Configure the MCP server in settings.json
You can configure MCP servers at the global level in the `~/.gemini/settings.json` file or in your project's root directory, create or open the `.gemini/settings.json` file. Within the file, add the `mcpServers` configuration block.
You can configure MCP servers in your `settings.json` file in two main ways: through the top-level `mcpServers` object for specific server definitions, and through the `mcp` object for global settings that control server discovery and execution.
#### Global MCP Settings (`mcp`)
The `mcp` object in your `settings.json` allows you to define global rules for all MCP servers.
- **`mcp.serverCommand`** (string): A global command to start an MCP server.
- **`mcp.allowed`** (array of strings): A whitelist of MCP server names to allow. If this is set, only servers from this list (matching the keys in the `mcpServers` object) will be connected to.
- **`mcp.excluded`** (array of strings): A blacklist of MCP server names to exclude. Servers in this list will not be connected to.
**Example:**
```json
{
"mcp": {
"allowed": ["my-trusted-server"],
"excluded": ["experimental-server"]
}
}
```
#### Server-Specific Configuration (`mcpServers`)
The `mcpServers` object is where you define each individual MCP server you want the CLI to connect to.
### Configuration Structure
@@ -667,9 +690,13 @@ await server.connect(transport);
This can be included in `settings.json` under `mcpServers` with:
```json
"nodeServer": {
"command": "node",
"args": ["filename.ts"],
{
"mcpServers": {
"nodeServer": {
"command": "node",
"args": ["filename.ts"]
}
}
}
```

32
docs/tools/shell.md
View File

@@ -66,16 +66,16 @@ When `run_shell_command` executes a command, it sets the `GEMINI_CLI=1` environm
## Command Restrictions
You can restrict the commands that can be executed by the `run_shell_command` tool by using the `coreTools` and `excludeTools` settings in your configuration file.
You can restrict the commands that can be executed by the `run_shell_command` tool by using the `tools.core` and `tools.exclude` settings in your configuration file.
- `coreTools`: To restrict `run_shell_command` to a specific set of commands, add entries to the `coreTools` list in the format `run_shell_command(<command>)`. For example, `"coreTools": ["run_shell_command(git)"]` will only allow `git` commands. Including the generic `run_shell_command` acts as a wildcard, allowing any command not explicitly blocked.
- `excludeTools`: To block specific commands, add entries to the `excludeTools` list in the format `run_shell_command(<command>)`. For example, `"excludeTools": ["run_shell_command(rm)"]` will block `rm` commands.
- `tools.core`: To restrict `run_shell_command` to a specific set of commands, add entries to the `core` list under the `tools` category in the format `run_shell_command(<command>)`. For example, `"tools": {"core": ["run_shell_command(git)"]}` will only allow `git` commands. Including the generic `run_shell_command` acts as a wildcard, allowing any command not explicitly blocked.
- `tools.exclude`: To block specific commands, add entries to the `exclude` list under the `tools` category in the format `run_shell_command(<command>)`. For example, `"tools": {"exclude": ["run_shell_command(rm)"]}` will block `rm` commands.
The validation logic is designed to be secure and flexible:
1. **Command Chaining Disabled**: The tool automatically splits commands chained with `&&`, `||`, or `;` and validates each part separately. If any part of the chain is disallowed, the entire command is blocked.
2. **Prefix Matching**: The tool uses prefix matching. For example, if you allow `git`, you can run `git status` or `git log`.
3. **Blocklist Precedence**: The `excludeTools` list is always checked first. If a command matches a blocked prefix, it will be denied, even if it also matches an allowed prefix in `coreTools`.
3. **Blocklist Precedence**: The `tools.exclude` list is always checked first. If a command matches a blocked prefix, it will be denied, even if it also matches an allowed prefix in `tools.core`.
### Command Restriction Examples
@@ -85,7 +85,9 @@ To allow only `git` and `npm` commands, and block all others:
```json
{
"coreTools": ["run_shell_command(git)", "run_shell_command(npm)"]
"tools": {
"core": ["run_shell_command(git)", "run_shell_command(npm)"]
}
}
```
@@ -99,8 +101,10 @@ To block `rm` and allow all other commands:
```json
{
"coreTools": ["run_shell_command"],
"excludeTools": ["run_shell_command(rm)"]
"tools": {
"core": ["run_shell_command"],
"exclude": ["run_shell_command(rm)"]
}
}
```
@@ -110,12 +114,14 @@ To block `rm` and allow all other commands:
**Blocklist takes precedence**
If a command prefix is in both `coreTools` and `excludeTools`, it will be blocked.
If a command prefix is in both `tools.core` and `tools.exclude`, it will be blocked.
```json
{
"coreTools": ["run_shell_command(git)"],
"excludeTools": ["run_shell_command(git push)"]
"tools": {
"core": ["run_shell_command(git)"],
"exclude": ["run_shell_command(git push)"]
}
}
```
@@ -124,11 +130,13 @@ If a command prefix is in both `coreTools` and `excludeTools`, it will be blocke
**Block all shell commands**
To block all shell commands, add the `run_shell_command` wildcard to `excludeTools`:
To block all shell commands, add the `run_shell_command` wildcard to `tools.exclude`:
```json
{
"excludeTools": ["run_shell_command"]
"tools": {
"exclude": ["run_shell_command"]
}
}
```