GitHub Security Agent MCP

A community-friendly, agentic GitHub security auditing and remediation platform with multiple ways to investigate, plan, fix and verify security issues.

Future roadmap: See FUTURE_PLAN.md for the planned AI-assisted security evaluation pipeline, including LLM analysis, remediation planning, deterministic execution, verification, LLM-as-Judge evaluation and quality/safety scoring.

Features and ways to use it

This project is intentionally not a single security script. The same security issue can be handled through different interfaces depending on how much automation, AI reasoning or integration you need.

Multiple ways to tackle the same security issue

                         GitHub Security Issue
                                  │
             ┌────────────────────┼────────────────────┐
             │                    │                    │
             ▼                    ▼                    ▼
        Claude Code           Cursor              MCP Client
             │                    │                    │
             └────────────────────┼────────────────────┘
                                  ▼
                         Security Skills / Agents
                                  │
                     ┌────────────┼────────────┐
                     ▼            ▼            ▼
                  Hooks        Scripts       CI
                     │            │            │
                     └────────────┼────────────┘
                                  ▼
                          Deterministic Worker
                                  │
                       ┌──────────┴──────────┐
                       ▼                     ▼
                  Fix / PR              Verify
                       │                     │
                       └──────────┬──────────┘
                                  ▼
                           Security Re-audit
                                  │
                                  ▼
                            Before / After
                               Report

You can use the project as a local developer tool, AI-agent workflow, GitHub CI automation, MCP server, or combination of these.

Related MCP server: gitlumen-mcp

What it does

GitHub security alerts tell you that a problem exists. This project takes the next step: understand the finding, choose a conservative stable fix, verify it, and leave an auditable result.

It supports Dependabot, code scanning / CodeQL, secret scanning, stable dependency remediation, automated verification, direct fixes or PRs, draft/ready PRs, reports and bounded parallel repository workers.

The project is designed for individuals, teams, organisations and the wider developer community. It is not tied to a particular GitHub account.

Architecture

                  AI / Application Clients
             ┌──────────┬───────────┬──────────┐
             ▼          ▼           ▼          ▼
          Claude     Cursor       MCP        CLI
             │          │           │          │
             └──────────┼───────────┼──────────┘
                        ▼
                 Agentic Workflow
                        │
                  TS Orchestrator
                   sequencing only
                        │
        ┌───────────────┼────────────────┐
        ▼               ▼                ▼
   Audit script    Remediation       Verification
        │               │                │
        └───────────────┼────────────────┘
                        ▼
                    GitHub API
                        │
                 Commit / Pull Request
                        │
                        ▼
                 Security re-audit
                        │
                        ▼
                     Reports

Source-of-truth rule

The TypeScript orchestrator coordinates sequencing. It does not duplicate security operations.

• Skills define agent workflow and reasoning guidance.

• Agents define repository responsibilities.

• Scripts perform deterministic security collection, remediation and verification.

• Hooks enforce lifecycle safety gates.

• MCP exposes capabilities to compatible clients.

• Claude/Cursor provide reasoning where useful.

• GitHub API is authoritative for GitHub security state.

MCP server

MCP is a first-class feature. Clone this repository and run it as an MCP server locally, or host it as a service for an MCP-compatible application.

MCP tools

Mutation is fail-closed. It requires both execute=true and MCP_ALLOW_MUTATIONS=true. PR mode is recommended and the system never auto-merges.

Local MCP with stdio

git clone https://github.com/girijashankarj/garry-github-security-agent-mcp.git
cd garry-github-security-agent-mcp
npm install
cp .env.example .env
npm run mcp

MCP over Streamable HTTP

MCP_HOST=127.0.0.1 MCP_PORT=3000 npm run mcp:http

Endpoint:

http://127.0.0.1:3000/mcp

For remote hosting, use HTTPS and authentication/authorisation. Do not expose mutation-enabled MCP directly to the public internet.

MCP Inspector

npx @modelcontextprotocol/inspector npm run mcp

Claude integration

Claude is optional. The deterministic security engine works without Anthropic access.

Interactive:

claude

CI/non-interactive:

claude -p "Run the security audit workflow defined by this repository. Follow approved configuration and never auto-merge."

Claude Batch API

For large repository sets, use Batch as an analysis/planning layer:

Repositories → Claude Batch API → remediation plans
       → deterministic validation → max 10 workers
       → tests + security recheck → commit / PR

The Batch layer must not directly mutate repositories.

Local environment

cp .env.example .env

Example values are intentionally fake:

GITHUB_OWNER=example-owner
GITHUB_TOKEN=github_pat_REPLACE_WITH_YOUR_TOKEN
ANTHROPIC_API_KEY=sk-ant-REPLACE_WITH_YOUR_KEY
ANTHROPIC_MODEL=claude-sonnet-4-5
SECURITY_AUDIT_MAX_REPO_WORKERS=10
SECURITY_AUDIT_RUN_TESTS=true
SECURITY_AUDIT_FIX_MODE=pr
SECURITY_AUDIT_PR_MODE=draft
MCP_ALLOW_MUTATIONS=false
MCP_HOST=127.0.0.1
MCP_PORT=3000

.env is gitignored. Never commit credentials.

GitHub Actions / Claude CI

Sensitive values belong in GitHub Actions Secrets:

Non-sensitive configuration belongs in GitHub Actions Variables:

Never store tokens or API keys in Variables.

Stable remediation strategy

The project does not blindly upgrade dependencies to latest.

Use the smallest stable patched version that resolves the security finding.

The agent should use GitHub advisory data, inspect manifests and lockfiles, avoid unrelated dependency churn, avoid unnecessary major migrations, run verification, re-check security state and report unresolved findings honestly.

A successful commit is not proof that a vulnerability is fixed.

Operator controls

Interactive runs ask:

1. All repositories or selected repositories?

2. Default branch or PR?

3. Draft or ready PR?

4. Commit-message format?

5. Include before/after table?

6. Which test/build/lint suites should run?

Reports

temp/
└── security-count/
    └── YYYY-MM-DD/
        ├── report-YYYY-MM-DD-HHmmss-sss.json   # BEFORE
        └── report-YYYY-MM-DD-HHmmss-sss.json   # AFTER

Reports contain run metadata, operator choices, security counts, findings, changes, verification, commits/PRs, failures and unresolved issues.

Project structure

.claude/
├── CLAUDE.md
├── settings.json
├── agents/
│   ├── security-repository-agent.md
│   ├── test-agent.md
│   └── review-agent.md
├── hooks/
│   ├── pre-change-audit.sh
│   └── post-change-test.sh
└── skills/
    └── security-audit/
        └── SKILL.md

.cursor/
├── rules/
│   └── security-audit.mdc
└── skills/
    └── security-audit/
        └── SKILL.md

scripts/
├── audit-security.mjs
├── remediate-repo.mjs
├── verify-repo.mjs
├── post-change-verify.mjs
├── finalize-report.mjs
└── consistency-check.mjs

src/
├── mcp-server.ts
├── orchestrator.ts
├── github.ts
├── runtime.ts
├── report.ts
├── remediation.ts
├── pr.ts
├── types.ts
└── worker.ts

Scripts are reusable outside Claude. Claude Code, Cursor and MCP clients can add agentic reasoning around the same deterministic security operations.

Development

Requirements: Node.js 20+, Git, a GitHub token with appropriate permissions, and optional Anthropic access.

npm install
npm run build
npm test
npm run audit
npm run mcp
npm run mcp:http
node scripts/audit-security.mjs
node scripts/verify-repo.mjs
node scripts/consistency-check.mjs

Safety model

Agent / MCP client decides
          ↓
Deterministic script executes
          ↓
Hook checks lifecycle invariant
          ↓
Tests verify repository
          ↓
GitHub security state rechecked
          ↓
Report records evidence

Safety rules:

• Never print or commit credentials.

• Never silently expand repository scope.

• Never dismiss alerts merely to reduce counts.

• Never auto-merge.

• Never claim a vulnerability is fixed without verification.

• Isolate repository failures.

• Keep reports out of Git.

• Keep MCP mutations disabled by default.

• Prefer MCP discovery and planning before mutation.

Community use

This project is designed to work with any GitHub account or organisation. Configure the target through environment variables or GitHub Actions configuration rather than assuming a specific owner.

License

MIT