Secrets Detection MCP Server

MCP (Model Context Protocol) server that detects accidentally committed secrets, API keys, tokens, and credentials in your codebase using pattern matching and entropy analysis.

Features

• Pattern-Based Detection: 30+ pre-configured patterns (AWS, GitHub, JWT, databases, etc.)
• Entropy Analysis: Shannon entropy calculation to detect high-entropy strings
• Remediation Guidance: Detailed advice for each secret type
• Flexible Scanning: Directory/file scanning with configurable options
• Multiple Output Formats: JSON, Markdown, CSV, and summary reports
• Custom Patterns: Add your own detection patterns
• Type Safe: Full TypeScript with Zod validation

Quick Start

Option 1: Using npx (Recommended)

npx secrets-detection-mcp

Option 2: Install Globally

npm install -g secrets-detection-mcp
secrets-detection-mcp

Option 3: Use in MCP Client

(Claude Code, Qwen Code, Claude Desktop, Codex, Cursor, OpenCode, etc.) Add to your MCP client settings:

{
  "mcpServers": {
    "secrets-detection": {
      "command": "npx",
      "args": ["-y", "secrets-detection-mcp"]
    }
  }
}

Or if installed globally:

{
  "mcpServers": {
    "secrets-detection": {
      "command": "secrets-detection-mcp"
    }
  }
}

Available Tools

Once connected, you can use these 9 tools:

1. scan_directory - Scan Directory for Secrets

Scan a directory recursively for secrets.

Parameters:

{
  "path": "/path/to/directory",
  "depth": 5,
  "exclude_patterns": ["node_modules", "dist"],
  "include_hidden": false,
  "max_file_size": 10
}

2. scan_file - Scan Single File

Scan a single file for secrets.

Parameters:

{
  "path": "/path/to/file.env"
}

3. validate_secret_pattern - Validate Text

Check if text contains known secret patterns.

Parameters:

{
  "text": "AKIA1234567890ABCDEF",
  "pattern_type": "aws"
}

4. get_remediation_advice - Get Remediation Guidance

Get detailed remediation advice for a secret type.

Parameters:

{
  "secret_type": "aws"
}

Returns:

• Why the secret is dangerous
• How to revoke it
• Proper storage recommendations
• Code examples (wrong vs. right)
• Recommended tools
• Reference links

5. add_custom_pattern - Add Custom Pattern

Add a custom detection pattern.

Parameters:

{
  "name": "MY_SECRET",
  "regex": "SECRET_[A-Z0-9]{32}",
  "type": "custom",
  "severity": "high",
  "description": "My custom pattern"
}

6. set_detection_threshold - Set Entropy Threshold

Adjust the entropy detection threshold.

Parameters:

{
  "entropy_threshold": 4.0
}

Threshold Values:

• 3.5 - More sensitive (more findings)
• 4.0 - Default (balanced)
• 4.5 - Less sensitive (fewer findings)

7. get_detection_config - Get Configuration

View current detection configuration (no parameters).

8. exclude_false_positive - Whitelist False Positive

Add a finding to the whitelist (mark as false positive).

Parameters:

{
  "file_path": "/path/to/file.ts",
  "line_number": 42,
  "reason": "Test fixture, not a real secret"
}

9. generate_report - Generate Report

Format scan results in various formats.

Parameters:

{
  "findings": [...],
  "format": "markdown",
  "include_remediation": true
}

Supported Formats:

• json - Structured JSON
• markdown - Human-readable report
• csv - CSV format for Excel
• summary - Brief summary

Example Usage

Scan a Project Directory

Simply ask:

Scan my project directory for secrets: D:\my-project

AI Agent will automatically:

1. Call scan_directory with your path
2. Show you the results
3. Provide remediation advice if secrets found

Check Specific File

Is there any secrets in this file? D:\my-project\.env

Validate Text

Is this a secret? ghp_1234567890abcdef

Get Help for Exposed Secrets

I accidentally committed AWS credentials, what should I do?

Detected Secret Types

The MCP server can detect 30+ types of secrets:

| Type | Severity | Examples | |------|----------|----------| | AWS Access Key | Critical | AKIA... | | AWS Secret Key | Critical | AWS secret access keys | | GitHub Token | Critical | ghp_..., gho_..., ghu_..., ghr_... | | Database URI | Critical | mongodb://user:pass@host, postgres://..., mysql://... | | Private Key | Critical | -----BEGIN RSA PRIVATE KEY-----, OpenSSH, EC, PGP | | Stripe Key | Critical | sk_live_..., rk_live_... | | NPM Token | Critical | npm_... | | PyPI Token | Critical | pypi-... | | JWT Token | High | eyJ... | | API Key | High | Various API keys | | Password | High | Hardcoded passwords | | Slack Token | High | xoxb-..., xoxp-..., webhooks | | Google Key | High | AIza... | | SendGrid Key | High | SG.... | | Mailgun Key | High | key-... | | Twilio Token | High | Twilio account SID/auth token | | Generic Secret | Medium | Generic secret assignments | | Base64 Secret | Medium | Base64 encoded secrets |

Configuration

Default Exclude Patterns

These directories/files are excluded by default:

• .git/
• node_modules/
• dist/, build/
• vendor/
• *.min.js, *.min.css
• Binary files (.exe, .dll, .so, etc.)
• Images (.png, .jpg, .jpeg, .gif, etc.)
• Fonts (.woff, .woff2, .ttf, etc.)

Custom Exclusions

You can add custom exclusions when scanning:

{
  "path": "/path/to/dir",
  "exclude_patterns": ["vendor/", "*.log", "htmlcov/"]
}

Entropy Threshold

Default: 4.0 (lower = more sensitive)

• 3.5 - More sensitive (detects more potential secrets, may have more false positives)
• 4.0 - Default (balanced detection)
• 4.5 - Less sensitive (fewer findings, higher confidence)

Performance

• Scans ~100-500 files/second (depends on file size and content)
• Default file size limit: 10MB (configurable)
• Optimized regex caching for fast pattern matching
• Efficient Shannon entropy calculations

Project Structure

secrets-detection-mcp/
├── src/
│   ├── index.ts                 # MCP server entry point
│   ├── types.ts                 # Zod schemas & types
│   ├── detector/
│   │   ├── patternDetector.ts   # Pattern matching
│   │   ├── entropyDetector.ts   # Entropy analysis
│   │   └── patterns.json        # 30+ secret patterns
│   ├── scanner/
│   │   └── fileScanner.ts       # File/directory scanning
│   ├── analyzer/
│   │   ├── remediationAdvisor.ts # Remediation guidance
│   │   └── findingsProcessor.ts  # Findings processing
│   └── utils/
│       ├── config.ts            # Configuration
│       ├── logger.ts            # Logging
│       └── outputFormatter.ts   # Output formatting
├── tests/                       # Test suite
│   ├── detector.test.ts
│   ├── entropyDetector.test.ts
│   ├── scanner.test.ts
│   ├── analyzer.test.ts
│   └── fixtures/                # Test data
├── package.json
├── tsconfig.json
├── jest.config.json
├── LICENSE
├── CHANGELOG.md
└── README.md

Development

Want to contribute or modify?

# Clone the repo
git clone https://github.com/deja666/secrets-detection-mcp.git
cd secrets-detection-mcp

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Run in dev mode (watch)
npm run dev

# Start MCP server
npm start

Adding New Patterns

1. Edit src/detector/patterns.json
2. Add your pattern with metadata:

   {
     "name": "MY_CUSTOM_SECRET",
     "regex": "MY_SECRET_[A-Z0-9]{32}",
     "type": "custom",
     "severity": "high",
     "description": "My custom secret pattern"
   }

3. Write tests in tests/detector.test.ts
4. Run tests: npm test

Best Practices

What NOT to Do

// NEVER commit secrets to version control
const AWS_KEY = 'AKIA1234567890ABCDEF';
const db = mongoose.connect('mongodb://user:pass@host/db');

What TO Do

// Use environment variables
const AWS_KEY = process.env.AWS_ACCESS_KEY_ID;
const db = mongoose.connect(process.env.MONGODB_URI);

// Use secret management tools
// - AWS Secrets Manager
// - HashiCorp Vault
// - 1Password
// - Azure Key Vault

// Use .env files (NEVER commit them!)
// Add to .gitignore:
// .env
// .env.local
// .env.*.local

Troubleshooting

MCP Server Won't Connect

1. Check Node.js version (need 20+):

   node --version

2. Reinstall:

   npm uninstall -g secrets-detection-mcp
   npm install -g secrets-detection-mcp

3. Test manually:

   secrets-detection-mcp
   # Should output: "Secrets Detection MCP server running on stdio"

Too Many False Positives

Increase entropy threshold:

Set detection threshold to 4.5

Or exclude specific directories:

Scan D:\my-project but exclude htmlcov and tests directories

Not Finding Real Secrets

Lower the entropy threshold:

Set detection threshold to 3.5

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

How to Contribute

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT License - see LICENSE file for details.

Acknowledgments

Inspired by:

• TruffleHog
• detect-secrets
• git-secrets

References

• OWASP Secrets Management Cheat Sheet
• AWS Credential Best Practices
• GitHub Token Security

Support

• Bug Reports: https://github.com/deja666/secrets-detection-mcp/issues
• Feature Requests: https://github.com/deja666/secrets-detection-mcp/issues
• Documentation: https://github.com/deja666/secrets-detection-mcp#readme
• npm Package: https://www.npmjs.com/package/secrets-detection-mcp

Disclaimer

This tool is for legitimate security scanning of your own codebases or codebases you have explicit permission to scan. Do not use on repositories you don't own or have authorization to access.

The pattern detection is not exhaustive and should be used as part of a comprehensive security strategy. Always follow security best practices for secrets management.