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:

Call scan_directory with your path
Show you the results
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

Edit src/detector/patterns.json

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"
}

Write tests in tests/detector.test.ts
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

Check Node.js version (need 20+):
```
node --version
```

Reinstall:

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

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

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

License

MIT License - see LICENSE file for details.

Acknowledgments

Inspired by:

References

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.

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
.github		.github
src		src
tests		tests
.gitignore		.gitignore
.npmignore		.npmignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
jest.config.json		jest.config.json
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

Secrets Detection MCP Server

Features

Quick Start

Option 1: Using npx (Recommended)

Option 2: Install Globally

Option 3: Use in MCP Client

Available Tools

1. scan_directory - Scan Directory for Secrets

2. scan_file - Scan Single File

3. validate_secret_pattern - Validate Text

4. get_remediation_advice - Get Remediation Guidance

5. add_custom_pattern - Add Custom Pattern

6. set_detection_threshold - Set Entropy Threshold

7. get_detection_config - Get Configuration

8. exclude_false_positive - Whitelist False Positive

9. generate_report - Generate Report

Example Usage

Scan a Project Directory

Check Specific File

Validate Text

Get Help for Exposed Secrets

Detected Secret Types

Configuration

Default Exclude Patterns

Custom Exclusions

Entropy Threshold

Performance

Project Structure

Development

Adding New Patterns

Best Practices

What NOT to Do

What TO Do

Troubleshooting

MCP Server Won't Connect

Too Many False Positives

Not Finding Real Secrets

Contributing

How to Contribute

License

Acknowledgments

References

Support

Disclaimer

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages