{"id":28804761,"url":"https://github.com/gitguardian/gg-mcp","last_synced_at":"2025-08-27T04:04:27.864Z","repository":{"id":299437016,"uuid":"983382162","full_name":"GitGuardian/gg-mcp","owner":"GitGuardian","description":"MCP server for scanning and remediating hardcoded secrets using GitGuardian’s API. Detect over 500 secret types and prevent credential leaks before code goes public.","archived":false,"fork":false,"pushed_at":"2025-08-21T07:22:47.000Z","size":264,"stargazers_count":21,"open_issues_count":0,"forks_count":4,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-08-21T09:37:27.373Z","etag":null,"topics":["mcp","mcp-server","secrets","security"],"latest_commit_sha":null,"homepage":"https://www.gitguardian.com/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GitGuardian.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-14T09:51:22.000Z","updated_at":"2025-08-21T07:21:12.000Z","dependencies_parsed_at":"2025-08-21T09:12:07.702Z","dependency_job_id":"42db6c70-96a9-4ab4-9c14-c2804242bd59","html_url":"https://github.com/GitGuardian/gg-mcp","commit_stats":null,"previous_names":["gitguardian/gg-mcp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/GitGuardian/gg-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GitGuardian%2Fgg-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GitGuardian%2Fgg-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GitGuardian%2Fgg-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GitGuardian%2Fgg-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GitGuardian","download_url":"https://codeload.github.com/GitGuardian/gg-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GitGuardian%2Fgg-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272289029,"owners_count":24907797,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-27T02:00:09.397Z","response_time":76,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mcp","mcp-server","secrets","security"],"created_at":"2025-06-18T09:30:43.844Z","updated_at":"2025-08-27T04:04:27.854Z","avatar_url":"https://github.com/GitGuardian.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GitGuardian MCP Server\n\nStay focused on building your product while your AI assistant handles the security heavy lifting with GitGuardian's comprehensive protection.\n\nThis MCP server enables your AI agent to scan projects using GitGuardian's industry-leading API, featuring over 500 secret detectors to prevent credential leaks before they reach public repositories.\n\nResolve security incidents without context switching to the GitGuardian console. Take advantage of rich contextual data to enhance your agent's remediation capabilities, enabling rapid resolution and automated removal of hardcoded secrets.\n\n## Disclaimer\n\n\u003e [!CAUTION]\n\u003e MCP servers are an emerging and rapidly evolving technology. While they can significantly boost productivity and improve the developer experience, their use with various agents and models should always be supervised.\n\u003e\n\u003e Agents act on your behalf and under your responsibility. Always use MCP servers from trusted sources (just as you would with any dependency), and carefully review agent actions when they interact with MCP server tools.\n\u003e\n\u003e To better assist you in safely using this server, we have:\n\u003e\n\u003e (1) Designed our MCP server to operate with \"read-only\" permissions, minimizing the access level granted to your agent. This helps ensure that, even if the agent tries to perform unintended actions, its capabilities remain limited to safe, non-destructive operations.\n\u003e\n\u003e (2) Released this official MCP server to ensure you are using a legitimate and trusted implementation.\n\n## Features supported\n\n- **Secret Scanning**: Scan code for leaked secrets, credentials, and API keys\n- **Incident Management**: View security incidents related to the project you are currently working.\n- **Honeytokens**: Create honeytokens to detect unauthorized access\n- **Authentication Management**: Get authenticated user information and token details\n- **Token Management**: Revoke current API tokens\n\n\u003e **Want more features?** Have a use case that's not covered? We'd love to hear from you! Submit your ideas and feedback by [opening an issue on GitHub](https://github.com/GitGuardian/gg-mcp/issues) to help us prioritize new MCP server capabilities.\n\n## Prompts examples\n\n`Remediate all incidents related to my project`\n\n`Scan this codebase for any leaked secrets or credentials`\n\n`Check if there are any new security incidents assigned to me`\n\n`Help me understand this security incident and provide remediation steps`\n\n`List all my active honeytokens`\n\n`Generate a new honeytoken for monitoring AWS credential access`\n\n`Show me my most recent honeytoken and help me embed it in my codebase`\n\n`Create a honeytoken named 'dev-database' and hide it in config files`\n\n## Prerequisites\n\nBefore installing the GitGuardian MCP servers, ensure you have the following prerequisites:\n\n- **uv**: This project uses uv for package installation and dependency management.\n  Install uv by following the instructions at: https://docs.astral.sh/uv/getting-started/installation/\n\n## Installation\n\nBelow are instructions for installing the GitGuardian MCP servers with various AI editors and interfaces.\n\nThe MCP server supports both GitGuardian SaaS and self-hosted instances.\n\n### Installation with Cursor\n\n**Quick Install with One-Click Buttons** (Cursor \u003e= 1.0):\n\nFor Developer MCP Server:\n\n[![Install Developer MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=GitGuardianDeveloper\u0026config=eyJjb21tYW5kIjoidXZ4IC0tZnJvbSBnaXQraHR0cHM6Ly9naXRodWIuY29tL0dpdEd1YXJkaWFuL2dnLW1jcC5naXQgZGV2ZWxvcGVyLW1jcC1zZXJ2ZXIiLCJlbnYiOnt9fQ%3D%3D)\n\n\u003e **Note**: The one-click install sets up the default US SaaS configuration. For EU SaaS or self-hosted instances, you'll need to manually add environment variables as shown in the [Configuration section](#configuration-for-different-gitguardian-instances).\n\n**Manual Configuration**:\n\n1. Edit your Cursor MCP configuration file located at `~/.cursor/mcp.json`\n\n2. Add the GitGuardian MCP server configuration:\n\n   ```json\n   {\n     \"mcpServers\": {\n       \"GitGuardianDeveloper\": {\n         \"command\": \"uvx\",\n         \"args\": [\n           \"--from\",\n           \"git+https://github.com/GitGuardian/gg-mcp.git\",\n           \"developer-mcp-server\"\n         ]\n       }\n     }\n   }\n   ```\n\n### Installation with Claude Desktop\n\n1. Edit your Claude Desktop MCP configuration file located at:\n\n   - macOS: `~/Library/Application Support/Claude Desktop/mcp.json`\n   - Windows: `%APPDATA%\\Claude Desktop\\mcp.json`\n\n2. Add the GitGuardian MCP server configuration:\n\n   ```json\n   {\n     \"mcpServers\": {\n       \"GitGuardianDeveloper\": {\n         \"command\": \"/path/to/uvx\",\n         \"args\": [\n           \"--from\",\n           \"git+https://github.com/GitGuardian/gg-mcp.git\",\n           \"developer-mcp-server\"\n         ]\n       }\n     }\n   }\n   ```\n\n3. Replace `/path/to/uvx` with the **absolute path** to the uvx executable on your system.\n\n   \u003e ⚠️ **WARNING**: For Claude Desktop, you must specify the full absolute path to the `uvx` executable, not just `\"command\": \"uvx\"`. This is different from other MCP clients.\n\n4. Restart Claude Desktop to apply the changes.\n\n### Installation with Windsurf\n\nTo use the GitGuardian MCP server with [Windsurf](https://www.windsurf.ai/):\n\n1. Edit your Windsurf MCP configuration file located at:\n\n   - macOS: `~/Library/Application Support/Windsurf/mcp.json`\n   - Windows: `%APPDATA%\\Windsurf\\mcp.json`\n   - Linux: `~/.config/Windsurf/mcp.json`\n\n2. Add the following entry to the configuration file:\n\n   ```json\n   {\n     \"mcp\": {\n       \"servers\": {\n         \"GitGuardianDeveloper\": {\n           \"type\": \"stdio\",\n           \"command\": \"uvx\",\n           \"args\": [\n             \"--from\",\n             \"git+https://github.com/GitGuardian/gg-mcp.git\",\n             \"developer-mcp-server\"\n           ]\n         }\n       }\n     }\n   }\n   ```\n\n### Installation with Zed Editor\n\n1. Edit your Zed MCP configuration file located at:\n\n   - macOS: `~/Library/Application Support/Zed/mcp.json`\n   - Linux: `~/.config/Zed/mcp.json`\n\n2. Add the GitGuardian MCP server configuration:\n\n   ```json\n   {\n     \"GitGuardianDeveloper\": {\n       \"command\": {\n         \"path\": \"uvx\",\n         \"args\": [\n           \"--from\",\n           \"git+https://github.com/GitGuardian/gg-mcp.git\",\n           \"developer-mcp-server\"\n         ]\n       }\n     }\n   }\n   ```\n\n## Authentication Process\n\n1. When you start the server, it will automatically open a browser window to authenticate with GitGuardian\n2. After you log in to GitGuardian and authorize the application, you'll be redirected back to the local server\n3. The authentication token will be securely stored for future use\n4. The next time you start the server, it will reuse the stored token without requiring re-authentication\n\n## Configuration for Different GitGuardian Instances\n\nThe MCP server uses OAuth authentication and defaults to GitGuardian SaaS (US region) at `https://dashboard.gitguardian.com`. For other instances, you'll need to specify the URL:\n\n### Environment Variables\n\nThe following environment variables can be configured:\n\n| Variable | Description | Default | Example |\n|----------|-------------|---------|---------|\n| `GITGUARDIAN_URL` | GitGuardian instance URL | `https://dashboard.gitguardian.com` | `https://dashboard.eu1.gitguardian.com` |\n| `GITGUARDIAN_CLIENT_ID` | OAuth client ID | `ggshield_oauth` | `my-custom-oauth-client` |\n| `GITGUARDIAN_SCOPES` | OAuth scopes to request | Auto-detected based on instance type | `scan,incidents:read,sources:read,honeytokens:read,honeytokens:write` |\n| `GITGUARDIAN_TOKEN_NAME` | Name for the OAuth token | Auto-generated based on server type | `\"Developer MCP Token\"` |\n| `GITGUARDIAN_TOKEN_LIFETIME` | Token lifetime in days | `30` | `60` or `never` |\n\n### Self-Hosted GitGuardian\n\nFor self-hosted GitGuardian instances, add the `GITGUARDIAN_URL` environment variable to your MCP configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"GitGuardianDeveloper\": {\n      \"command\": \"uvx\",\n      \"args\": [\"--from\", \"git+https://github.com/GitGuardian/gg-mcp.git\", \"developer-mcp-server\"],\n      \"env\": {\n        \"GITGUARDIAN_URL\": \"https://dashboard.gitguardian.mycorp.local\"\n      }\n    }\n  }\n}\n```\n\n### Self-Hosted with Honeytoken Support\n\nIf your self-hosted instance has honeytokens enabled and your user has the required permissions (\"manager\" role), you can explicitly request honeytoken scopes:\n\n```json\n{\n  \"mcpServers\": {\n    \"GitGuardianDeveloper\": {\n      \"command\": \"uvx\",\n      \"args\": [\"--from\", \"git+https://github.com/GitGuardian/gg-mcp.git\", \"developer-mcp-server\"],\n      \"env\": {\n        \"GITGUARDIAN_URL\": \"https://dashboard.gitguardian.mycorp.local\",\n        \"GITGUARDIAN_SCOPES\": \"scan,incidents:read,sources:read,honeytokens:read,honeytokens:write\"\n      }\n    }\n  }\n}\n```\n\n### GitGuardian EU Instance\n\nFor the GitGuardian EU instance, use:\n\n```json\n{\n  \"mcpServers\": {\n    \"GitGuardianDeveloper\": {\n      \"command\": \"uvx\",\n      \"args\": [\"--from\", \"git+https://github.com/GitGuardian/gg-mcp.git\", \"developer-mcp-server\"],\n      \"env\": {\n        \"GITGUARDIAN_URL\": \"https://dashboard.eu1.gitguardian.com\"\n      }\n    }\n  }\n}\n```\n\n### Custom OAuth Client\n\nIf you have your own OAuth application configured in GitGuardian, you can specify a custom client ID:\n\n```json\n{\n  \"mcpServers\": {\n    \"GitGuardianDeveloper\": {\n      \"command\": \"uvx\",\n      \"args\": [\"--from\", \"git+https://github.com/GitGuardian/gg-mcp.git\", \"developer-mcp-server\"],\n      \"env\": {\n        \"GITGUARDIAN_CLIENT_ID\": \"my-custom-oauth-client\"\n      }\n    }\n  }\n}\n```\n\n## Development\n\nIf you want to contribute to this project or add new tools, please see the [Development Guide](DEVELOPMENT.md).\n\n## Testing\n\nThis project includes a comprehensive test suite to ensure functionality and prevent regressions.\n\n### Running Tests\n\n1. Run the test suite:\n   ```bash\n   uv run pytest\n   ```\n\nThis will run all tests and generate a coverage report showing which parts of the codebase are covered by tests.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgitguardian%2Fgg-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgitguardian%2Fgg-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgitguardian%2Fgg-mcp/lists"}