Skip to content

docs: fix claude mcp add command syntax and remove unsupported flags #59

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
petems wants to merge 1 commit into
base: master
Choose a base branch
from
Open

docs: fix claude mcp add command syntax and remove unsupported flags #59

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 20 additions & 6 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -156,15 +156,29 @@ Run these from the repo root so `$(pwd)` points to this project.
#### Claude Code (CLI)

```bash
# Minimal (pass env vars if needed)
claude mcp add pr-review -s user -- \
uv run --project "$(pwd)" -- mcp-github-pr-review
# Recommended: Using installed tool with environment variable from shell
claude mcp add pr-review --scope user --transport stdio --env GITHUB_TOKEN="${GITHUB_TOKEN}" -- \
mcp-github-pr-review

# Example with env var (GitHub token)
claude mcp add pr-review -s user -e GITHUB_TOKEN="$GITHUB_TOKEN" -- \
uv run --project "$(pwd)" -- mcp-github-pr-review
# With pagination limits
claude mcp add pr-review --scope user --transport stdio --env GITHUB_TOKEN="${GITHUB_TOKEN}" -- \
mcp-github-pr-review --max-comments 500 --max-pages 20

# Using uv run from project directory
claude mcp add pr-review --scope user --transport stdio --env GITHUB_TOKEN="${GITHUB_TOKEN}" -- \
uv run --project "$(pwd)" mcp-github-pr-review

# Using short flags
claude mcp add pr-review -s user -t stdio -e GITHUB_TOKEN="${GITHUB_TOKEN}" -- \
mcp-github-pr-review
```

**Important:**
- Format: `claude mcp add SERVER_NAME [OPTIONS] -- COMMAND [ARGS]`
- Server name comes FIRST, before any options
- All options (`--scope`, `--transport`, `--env`) come after server name but before `--`
- Supported MCP server flags: `--max-comments`, `--max-pages`, `--per-page`, `--max-retries`, `--env-file`

#### Codex CLI

Append to `~/.codex/config.toml`:
Expand Down
23 changes: 22 additions & 1 deletion docs/getting-started/quickstart.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,28 @@ echo "GITHUB_TOKEN=ghp_your_token" > .env
uv run mcp-github-pr-review
```

Once the server is running, connect it from your preferred MCP host (Claude Desktop, Codex CLI, Cursor, etc.). For tailored integration steps, visit [Editor Integrations](../guides/editor-integrations.md).
Once the server is running, connect it from your preferred MCP host (Claude Desktop, Codex CLI, Cursor, etc.).

## Register with Claude Code CLI

After installing, register the server with Claude Code:

```bash
# Install as a tool first
uv tool install mcp-github-pr-review

# Register with Claude Code CLI
claude mcp add pr-review --scope user --transport stdio --env GITHUB_TOKEN="${GITHUB_TOKEN}" -- \
mcp-github-pr-review
```

**Command structure:**
- Server name (`pr-review`) comes FIRST
- All options (`--scope`, `--transport`, `--env`) come after server name but before `--`
- The `--` separator divides configuration from the command
- Command and arguments come after `--`

For other hosts (Cursor, VS Code, etc.), visit [Editor Integrations](../guides/editor-integrations.md).
Comment on lines +30 to +49
Copy link
Contributor

@coderabbitai coderabbitai bot Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Clarify token sourcing when running via Claude CLI.

Line 22 writes .env in the repo root, but claude mcp add may execute from a different working directory, so auto-loading that .env may not apply. Consider adding a note to either export GITHUB_TOKEN in the shell or use --env-file /absolute/path/to/.env to avoid confusion.

✏️ Suggested doc tweak 
 # Register with Claude Code CLI
@@
 # Register with Claude Code CLI
 claude mcp add pr-review --scope user --transport stdio --env GITHUB_TOKEN="${GITHUB_TOKEN}" -- \
   mcp-github-pr-review
+
+# If you rely on a .env file, pass an absolute path:
+# claude mcp add pr-review --scope user --transport stdio --env-file /abs/path/to/.env -- \
+#   mcp-github-pr-review
🤖 Prompt for AI Agents 
In `@docs/getting-started/quickstart.md` around lines 30 - 49, Update the
"Register with Claude Code CLI" section to clarify how GITHUB_TOKEN is sourced
when the CLI runs from a different working directory: mention that writing a
.env in the repo root does not guarantee the token is loaded by the claude mcp
add pr-review command, and instruct users to either export GITHUB_TOKEN in their
shell beforehand (e.g., export GITHUB_TOKEN=...) or use the claude flag
--env-file with an absolute path to the .env file (e.g., --env-file
/absolute/path/to/.env) instead of relying on a relative .env; reference the
exact command and flags (claude mcp add pr-review, --env, --env-file, --) so
readers know where to apply the change.


## Verify a Connection

Expand Down
231 changes: 227 additions & 4 deletions docs/guides/local-stdio.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,24 +4,247 @@ The fastest way to run the server is locally over stdio, which is the default tr

## Setup Checklist

1. Install the package (`uv add mcp-github-pr-review`).
1. Install the package (`uv tool install mcp-github-pr-review` or `uv add mcp-github-pr-review`).
2. Export `GITHUB_TOKEN` in your shell or write it to `.env`.
3. Launch the entry point:
```bash
mcp-github-pr-review --log-level info
mcp-github-pr-review
```
4. Register the server with your host using the command above.
4. Register the server with your host using the configuration commands below.

## Optional Flags

| Flag | Description |
| --- | --- |
| `--log-file PATH` | Write structured logs to `PATH` in addition to stderr. |
| `--env-file PATH` | Load environment variables from a custom .env file. |
| `--max-comments N` | Override `PR_FETCH_MAX_COMMENTS` for the process lifetime. |
| `--max-pages N` | Override `PR_FETCH_MAX_PAGES`. |
| `--per-page N` | Override `HTTP_PER_PAGE` (GitHub API page size, 1-100). |
| `--max-retries N` | Override `HTTP_MAX_RETRIES` (retry limit for transient errors). |

## Host Configuration Examples

Below are configuration examples for popular MCP hosts. All examples assume:
- You've installed the package (`uv add mcp-github-pr-review` or globally via `uvx`)
- Your `GITHUB_TOKEN` is exported in your shell or available in `.env`

### CLI-Based Configuration (Recommended)

Several MCP hosts support adding servers via command-line interface, which is often faster and less error-prone than manual JSON editing.

#### Claude Code CLI

Add the server using the `claude mcp add` command:

```bash
# Basic setup (inherits GITHUB_TOKEN from shell environment)
claude mcp add github-pr-review --scope user --transport stdio --env GITHUB_TOKEN="${GITHUB_TOKEN}" -- mcp-github-pr-review

# With explicit environment variable (not recommended - use shell env instead)
claude mcp add github-pr-review --scope user --transport stdio --env GITHUB_TOKEN=your_token_here -- mcp-github-pr-review

# With additional flags for pagination limits
claude mcp add github-pr-review --scope user --transport stdio --env GITHUB_TOKEN="${GITHUB_TOKEN}" -- mcp-github-pr-review --max-comments 500 --max-pages 20

# Using uvx (if not installed as a tool)
claude mcp add github-pr-review --scope user --transport stdio --env GITHUB_TOKEN="${GITHUB_TOKEN}" -- uvx mcp-github-pr-review

# Using short flags
claude mcp add github-pr-review -s user -t stdio -e GITHUB_TOKEN="${GITHUB_TOKEN}" -- mcp-github-pr-review
```

**Key points:**
- Format: `claude mcp add SERVER_NAME [OPTIONS] -- COMMAND [ARGS]`
- The server name comes FIRST, before any options
- All options (`--scope`, `--transport`, `--env`) come after the server name but before `--`
- The `--` separator divides configuration from the command to execute
- Use `--scope user` (or `-s user`) for global availability (recommended)
- Use `--transport stdio` (or `-t stdio`) to specify stdio transport (default)
- Supported MCP server flags: `--max-comments`, `--max-pages`, `--per-page`, `--max-retries`, `--env-file`
- The `--log-level` flag is NOT supported (it was shown in error in previous versions)

Comment on lines +35 to +65
Copy link
Contributor

@coderabbitai coderabbitai bot Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Add a note for .env when the working directory isn’t the repo root.

Some hosts (or Claude CLI) may launch the command from a different working directory, so .env auto-loading can be missed. Consider mentioning --env-file /abs/path/to/.env as a reliable alternative when not exporting GITHUB_TOKEN in the shell.

✏️ Suggested doc tweak 
 # With additional flags for pagination limits
 claude mcp add github-pr-review --scope user --transport stdio --env GITHUB_TOKEN="${GITHUB_TOKEN}" -- mcp-github-pr-review --max-comments 500 --max-pages 20
+
+# If relying on a .env file outside the working directory:
+# claude mcp add github-pr-review --scope user --transport stdio --env-file /abs/path/to/.env -- \
+#   mcp-github-pr-review
🤖 Prompt for AI Agents 
In `@docs/guides/local-stdio.md` around lines 35 - 65, Add a brief note to the
"Claude Code CLI" section near the examples for `claude mcp add` explaining that
when the CLI or host launches the command from a different working directory,
automatic `.env` loading can be missed and recommending using `--env-file
/abs/path/to/.env` as a reliable alternative to exporting GITHUB_TOKEN in the
shell; mention this alongside the supported MCP server flags and reference the
`--env-file` option and `GITHUB_TOKEN` env usage so readers see where to apply
it.

#### VS Code CLI (Native MCP)

Add the server using the `code` command:

```bash
# Basic setup with uvx
code --add-mcp '{"name":"github-pr-review","command":"uvx","args":["mcp-github-pr-review"]}'

# With environment variable
code --add-mcp '{"name":"github-pr-review","command":"uvx","args":["mcp-github-pr-review"],"env":{"GITHUB_TOKEN":"your_token_here"}}'

# With pagination limits
code --add-mcp '{"name":"github-pr-review","command":"uvx","args":["mcp-github-pr-review","--max-comments","500","--max-pages","20"]}'
```

**Note:** Requires VS Code 1.102+ with native MCP support. The JSON must be properly escaped in the shell.

#### Cursor CLI (Interactive)

Use Cursor's interactive MCP commands:

```bash
# Open interactive MCP menu to browse and configure servers
cursor /mcp list

# Enable a configured MCP server
cursor /mcp enable github-pr-review

# Disable an MCP server
cursor /mcp disable github-pr-review
```

**Note:** These commands require Cursor CLI (January 2026+). For initial setup, you'll still need to create the JSON configuration first, then use these commands to manage it.

### Manual JSON Configuration

For hosts without CLI support, or if you prefer manual configuration:

#### Claude Desktop (Claude Code)

**Note:** Prefer using `claude mcp add` CLI command (see above). For manual configuration, edit:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
"mcpServers": {
"github-pr-review": {
"command": "uvx",
"args": ["mcp-github-pr-review"],
"env": {
"GITHUB_TOKEN": "your_github_token_here"
}
}
}
}
```

**Alternative with installed package:**
```json
{
"mcpServers": {
"github-pr-review": {
"command": "mcp-github-pr-review",
"args": ["--max-comments", "500", "--max-pages", "20"]
}
}
}
```

#### Cursor IDE

**Note:** Use `cursor /mcp list` CLI command for interactive management (see CLI section above). For manual configuration, create:
- Project-level: `.cursor/mcp.json` in your project directory
- Global: `~/.cursor/mcp.json` in your home directory

```json
{
"mcpServers": {
"github-pr-review": {
"command": "uvx",
"args": ["mcp-github-pr-review"],
"env": {
"GITHUB_TOKEN": "your_github_token_here"
}
}
}
}
```

After creating the file, use `cursor /mcp enable github-pr-review` to activate it. Cursor also supports one-click setup for curated MCP servers.

#### Cline (VS Code Extension)

**Manual configuration:**
1. Click the "MCP Servers" icon in Cline's top navigation bar
2. Select the "Configure" tab
3. Click "Configure MCP Servers" button
4. Add to `cline_mcp_settings.json`:

```json
{
"mcpServers": {
"github-pr-review": {
"command": "uvx",
"args": ["mcp-github-pr-review"],
"env": {
"GITHUB_TOKEN": "your_github_token_here"
}
}
}
}
```

**Note:** Cline supports `${workspaceFolder}` variable for dynamic workspace paths if needed for log files.

#### Continue.dev (VS Code Extension)

**Manual configuration:** Create directory `.continue/mcpServers/` at your workspace root and add `github-pr-review.json`:

```json
{
"name": "github-pr-review",
"command": "uvx",
"args": ["mcp-github-pr-review"],
"env": {
"GITHUB_TOKEN": "your_github_token_here"
}
}
```

**Alternative YAML format** (create `github-pr-review.yaml`):
```yaml
name: github-pr-review
command: uvx
args:
- mcp-github-pr-review
env:
GITHUB_TOKEN: your_github_token_here
```

**Note:** Continue.dev only supports MCP in agent mode. Files in `.continue/mcpServers/` are automatically picked up.

#### VS Code Native (GitHub Copilot)

**Note:** VS Code 1.102+ supports MCP natively. Use `code --add-mcp` CLI command (see CLI section above) or manually create `.vscode/mcp.json`:

```json
{
"mcpServers": {
"github-pr-review": {
"command": "uvx",
"args": ["mcp-github-pr-review"],
"env": {
"GITHUB_TOKEN": "your_github_token_here"
}
}
}
}
```

You can also use VS Code Command Palette: type `@mcp` in Extensions view or run "MCP: Browse Servers" / "MCP: List Servers" commands.

### Security Best Practices

**Never commit tokens directly in configuration files.** Use one of these approaches:

1. **Environment variable reference** (if supported by your host):
```json
"env": {
"GITHUB_TOKEN": "${GITHUB_TOKEN}"
}
```

2. **Keep token in shell environment only** and omit the `env` block entirely (works if the command inherits your shell environment)

3. **Use `.env` file** in your project root (server will automatically load it)

## Troubleshooting

- **401 Unauthorized**: Validate token scopes and ensure you are not mixing fine-grained and classic tokens.
- **Timeouts**: Increase `HTTP_MAX_RETRIES` and review network firewall policies.
- **Input Path Errors**: Upgrade to the latest version to pick up improvements in Dulwich-based repository detection.
- **Server not appearing**: Restart your MCP host after adding configuration. For Claude Desktop, quit and reopen the application.
- **Permission errors**: Ensure `uvx` or `mcp-github-pr-review` is in your PATH and executable.
55 changes: 46 additions & 9 deletions docs/reference/cli.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,15 +4,52 @@ The package installs the console script `mcp-github-pr-review`. The CLI accepts

```text
Usage: mcp-github-pr-review [OPTIONS]

Run the GitHub PR Review MCP server over stdio.

Options:
--env-file ENV_FILE Optional path to a .env file to load before starting the server.
--max-pages MAX_PAGES Override PR_FETCH_MAX_PAGES for this process.
--max-comments MAX_COMMENTS
Override PR_FETCH_MAX_COMMENTS for this process.
--per-page PER_PAGE Override HTTP_PER_PAGE for this process.
--max-retries MAX_RETRIES
Override HTTP_MAX_RETRIES for this process.
-h, --help Show this help message and exit.
```

| Option | Description |
| --- | --- |
| `--log-level {debug,info,warning,error}` | Set logging verbosity. Defaults to `info`. |
| `--log-file PATH` | Append log output to `PATH`. Stderr remains enabled. |
| `--max-pages N` | Override `PR_FETCH_MAX_PAGES` for this process. |
| `--max-comments N` | Override `PR_FETCH_MAX_COMMENTS` for this process. |
| `--json-logs` | Emit JSON formatted log lines. |
| `--help` | Show usage information. |
## Options

| Option | Type | Description |
| --- | --- | --- |
| `--env-file PATH` | string | Load environment variables from a custom `.env` file path. |
| `--max-pages N` | integer | Override `PR_FETCH_MAX_PAGES` for this process (default: 50). Must be positive. |
| `--max-comments N` | integer | Override `PR_FETCH_MAX_COMMENTS` for this process (default: 2000). Must be positive. |
| `--per-page N` | integer | Override `HTTP_PER_PAGE` for this process (default: 100, max: 100). Must be positive. |
| `--max-retries N` | integer | Override `HTTP_MAX_RETRIES` for this process (default: 3). Must be positive. |
| `-h, --help` | - | Show usage information and exit. |

## Examples

```bash
# Run with default settings
mcp-github-pr-review

# Load custom environment file
mcp-github-pr-review --env-file /path/to/.env

# Override pagination limits
mcp-github-pr-review --max-pages 20 --max-comments 500

# Adjust API behavior
mcp-github-pr-review --per-page 50 --max-retries 5
```

## Environment Variables

Command-line flags take precedence over environment variables. Environment variables can be set in:
- Shell environment
- `.env` file in the current directory (auto-loaded)
- Custom `.env` file via `--env-file`

All options can also be provided via environment variables. Command-line flags take precedence over `.env` or shell variables.
See [Environment Reference](environment.md) for the complete list of supported environment variables.
Loading