Transform your AI workflows into secure and organized development with the ShadowGit MCP Server. This MCP server provides AI assistants with read-only access to ShadowGit repositories and enables clean, Session API-driven commits, making debugging and code analysis safer and more auditable.

How to use

You interact with the ShadowGit MCP Server through an MCP client. The server runs on demand and communicates via standard input and output, so there is no persistent daemon to manage. Use the Session API to pause automatic commits, perform changes, and then create clean, organized checkpoints that your AI helper can push as commits.

How to install

Prerequisites you need before installing the MCP server.

# Install the MCP server globally
npm install -g shadowgit-mcp-server

Optional: verify installation

shadowgit-mcp-server --version

## Configuration and usage notes

Configure the environment to control how the MCP server runs and how it reports its activity. The following environment variables are supported:

- SHADOWGIT\_TIMEOUT: Command execution timeout in milliseconds (default: 10000)

- SHADOWGIT\_SESSION\_API: Session API URL (default: http://localhost:45289/api)

- SHADOWGIT\_LOG\_LEVEL: Log level (debug, info, warn, error; default: info)

- SHADOWGIT\_HINTS: Set to 0 to disable workflow hints in outputs (default: 1)

Example usage to customize timeouts and logging:

export SHADOWGIT_TIMEOUT=30000 # 30 second timeout export SHADOWGIT_LOG_LEVEL=debug # Enable debug logging export SHADOWGIT_HINTS=0 # Disable workflow banners for cleaner output

This MCP server is designed to be started by your MCP client when needed, and it will exit after the session concludes.

Security considerations

The ShadowGit MCP Server provides read-only access to safe git commands. It enforces protections to prevent destructive operations and restricts access to ShadowGit repositories only. Path traversal is blocked, dangerous flags are blocked, and commands are executed securely using execFileSync with array arguments to minimize injection risks.

Troubleshooting

Common issues and steps to resolve them.

No repositories found: Ensure the ShadowGit app is installed and has tracked repositories.

Session API offline: The ShadowGit app may not be running. Start a ShadowGit session or verify the Session API health.

Tools and capabilities

The MCP server exposes tools for interacting with ShadowGit repositories. You can list repositories, view git history, start and end AI work sessions, and create clean checkpoints.

Complete example workflow

1. List available repositories with your MCP client. 2) Start a session before making changes. 3) Inspect recent history if needed. 4) Edit code and implement changes. 5) Create a clean checkpoint commit after completing the task. 6) End the session to resume automatic commits.

Notes on usage patterns

Always follow the recommended four-step workflow: start_session, perform changes, checkpoint, end_session. Use descriptive commit titles and include detailed messages to explain what and why. End sessions properly to resume normal auto-commit behavior.

Development and contribution

If you want to contribute or run the MCP server locally for development, install dependencies, build, and run the local server as described by your project setup.

License

MIT License - see LICENSE file for details.

Available tools

list_repos

Lists all ShadowGit-tracked repositories.

git_command

Executes read-only git commands on a specific repository to inspect history, diffs, or blame information.

start_session

Begins an AI work session, pausing auto-commits until you checkpoint.

checkpoint

Creates a clean, organized commit snapshot of your work during a session.

end_session

Ends the AI work session and resumes auto-commits.