claude-warriorgpt-mcp

An MCP server that gives Claude Code one tool, ask_warriorgpt, which calls Wayne State's WarriorGPT API directly. Your Claude Code session stays on your Claude plan; only the tool call goes to WarriorGPT, so routine code generation does not count against your Claude usage.

It is a single Node file with no dependencies and works on macOS, Linux, and Windows.

Requirements

• Claude Code
• Node 18 or newer
• A WarriorGPT API key from https://warriorgpt.wayne.edu/developer/api-key

Install

To have Claude Code do it for you, tell it: "Follow the setup instructions at https://github.com/chrispelzer/claude-warriorgpt-mcp/blob/main/docs/agent-setup.md". It checks what is already done, runs the steps below, and stops for the ones only you can do, like entering your API key.

To install by hand:

1. Store your API key. The server reads the WARRIORGPT_API_KEY environment variable first, then falls back to the system keyring on macOS and Linux.

   macOS (Keychain). Run this and paste the key at the hidden prompt (-w must come last):

   security add-generic-password -U -a "$USER" -s warriorgpt-api-key -w
   

   Linux (Secret Service, e.g. GNOME Keyring or KWallet; secret-tool comes from the libsecret-tools or libsecret package). Paste the key at the prompt:

   secret-tool store --label="WarriorGPT API key" service warriorgpt-api-key
   

   Windows (user environment variable). In PowerShell, paste the key at the prompt, then open a new terminal so the variable is picked up:

   [Environment]::SetEnvironmentVariable('WARRIORGPT_API_KEY', (Read-Host 'WarriorGPT API key'), 'User')
   

   On any system you can instead export WARRIORGPT_API_KEY from your shell profile, as long as Claude Code is started from that shell.

2. Install the server globally:

   npm install -g github:chrispelzer/claude-warriorgpt-mcp
   

3. Register it with Claude Code for all projects.

   macOS and Linux:

   claude mcp add --scope user warriorgpt -- warriorgpt-mcp
   

   Windows (npm installs the command as a .cmd file, which needs cmd /c to start):

   claude mcp add --scope user warriorgpt -- cmd /c warriorgpt-mcp
   

4. Start a new Claude Code session and check /mcp shows warriorgpt as connected.

To update, rerun the npm install -g command; append #<commit or tag> to pin a version. If you manage Node with a version manager (asdf, nvm, fnm), the command is installed for the current Node version only, so reinstall after switching versions.

The tool

ask_warriorgpt sends a prompt to a WarriorGPT model and returns its reply. The model cannot read your repo or run commands, so give it everything it needs.

context_files, output_file, and files are what save Claude usage: file contents go from disk to WarriorGPT and back without passing through Claude. Claude should still read and check what was written.

With files, the model replies with one block per file: the full contents for a new file, or search/replace edits for an existing one, so a small change to a large file costs a few lines instead of a rewrite. The server checks every block before writing anything. If a block names a file not in files, edits a file that does not exist, or has search text that is missing or matches more than one place, nothing is written and the error lists each problem, so Claude can retry with a sharper prompt. Files with Windows line endings keep them.

Models:

• local.qwen3.8-27b: 262k context, best general coder (default)
• local.gpt-oss-120b: 131k context, stronger reasoning, slower
• local.laguna-s-2.1: 131k context; may not be reachable on the gateway yet
• local.gemma-4-31b: 131k context

Configuration

Pass variables at registration with claude mcp add ... -e WARRIORGPT_MODEL=local.gpt-oss-120b -- .... Avoid passing the API key this way: Claude Code stores it in plain text in its config file.

Usage log

Each call appends {ts, session, model, in, out} to usage.jsonl in the state directory, where session is the Claude Code session id. While a request is running, an active-<session> file exists there. A status line script can read both to show WarriorGPT activity and token totals.

The state directory is ~/.local/share/warriorgpt-mcp on macOS and Linux, and %LOCALAPPDATA%\warriorgpt-mcp on Windows.

Compared with OpenCode

You can also hand WarriorGPT work through an OpenCode subagent, which can search the repo and run code to check itself but costs far more per task. Use ask_warriorgpt when you can name the files involved. docs/opencode-subagent.md covers setup, trade-offs, and a benchmark of the two.

Telling Claude when to use it

Claude sees the tool description, but works best with a short rule in your CLAUDE.md, for example:

Use ask_warriorgpt for small, fully specified code generation (boilerplate, a straightforward function, tests for existing code). Attach inputs with context_files; set output_file for one new file, or list every file to create or change in files; then read and check the result. Keep design, debugging, and subtle logic with Claude.

Only in some sessions: a claude-warriorgpt alias

A rule in CLAUDE.md applies to every session. To delegate only when you choose to, put the rule in its own file and start Claude Code with it appended to the system prompt. Plain claude sessions are unaffected.

1. Copy warriorgpt-mode.md, which the npm install includes, to ~/.claude/. It tells Claude which tasks to send to WarriorGPT and which to keep. Edit your copy to taste; rerun the copy after an update to pick up changes.

   macOS and Linux:

   cp "$(npm root -g)/claude-warriorgpt-mcp/warriorgpt-mode.md" ~/.claude/
   

   Windows (PowerShell):

   Copy-Item "$(npm root -g)\claude-warriorgpt-mcp\warriorgpt-mode.md" "$HOME\.claude\"
   

2. Add the alias to your shell config.

   macOS and Linux (~/.zshrc or ~/.bashrc):

   alias claude-warriorgpt='claude --append-system-prompt-file ~/.claude/warriorgpt-mode.md'
   

   Windows (PowerShell profile; open it with notepad $PROFILE):

   function claude-warriorgpt { claude --append-system-prompt-file "$HOME\.claude\warriorgpt-mode.md" @args }
   

3. Open a new terminal and run claude-warriorgpt. Other arguments pass through, so claude-warriorgpt --continue works as usual.

If you also set up the OpenCode subagent, the same mode file is a good place for its rule, so the subagent is only used in these sessions too.

Troubleshooting

License

MIT