addinte templates and user guide
This commit is contained in:
Patryk Ciechanski
80
.github/ISSUE_TEMPLATE/bug_report.yml
vendored
Normal file
80
.github/ISSUE_TEMPLATE/bug_report.yml
vendored
Normal file
@@ -0,0 +1,80 @@
|
|||||||
|
name: 🐞 Bug Report
|
||||||
|
description: Create a report to help us improve
|
||||||
|
labels: ["bug", "needs-triage"]
|
||||||
|
body:
|
||||||
|
- type: markdown
|
||||||
|
attributes:
|
||||||
|
value: |
|
||||||
|
Thank you for taking the time to file a bug report! Please provide as much detail as possible to help us reproduce and fix the issue.
|
||||||
|
|
||||||
|
- type: input
|
||||||
|
id: version
|
||||||
|
attributes:
|
||||||
|
label: Project Version
|
||||||
|
description: "Which version are you using? (e.g., Docker image tag like `latest` or `v1.2.3`, or a git commit SHA)"
|
||||||
|
placeholder: "e.g., ghcr.io/beehiveinnovations/gemini-mcp-server:latest"
|
||||||
|
validations:
|
||||||
|
required: true
|
||||||
|
|
||||||
|
- type: textarea
|
||||||
|
id: description
|
||||||
|
attributes:
|
||||||
|
label: Bug Description
|
||||||
|
description: A clear and concise description of what the bug is.
|
||||||
|
placeholder: "When I run the `codereview` tool on a Python file with syntax errors, it hangs instead of reporting an error."
|
||||||
|
validations:
|
||||||
|
required: true
|
||||||
|
|
||||||
|
- type: textarea
|
||||||
|
id: reproduction-steps
|
||||||
|
attributes:
|
||||||
|
label: Steps to Reproduce
|
||||||
|
description: "Provide the exact steps to reproduce the behavior. Include the full command you ran."
|
||||||
|
placeholder: |
|
||||||
|
1. Create a file `test.py` with the content `def my_func(a,b)`
|
||||||
|
2. Run the command: `docker exec -i gemini-mcp-server python server.py`
|
||||||
|
3. Use Claude Desktop with gemini codereview tool on test.py
|
||||||
|
4. Observe the behavior...
|
||||||
|
validations:
|
||||||
|
required: true
|
||||||
|
|
||||||
|
- type: textarea
|
||||||
|
id: expected-behavior
|
||||||
|
attributes:
|
||||||
|
label: Expected Behavior
|
||||||
|
description: A clear and concise description of what you expected to happen.
|
||||||
|
placeholder: "I expected the tool to exit with an error message about the invalid Python syntax."
|
||||||
|
validations:
|
||||||
|
required: true
|
||||||
|
|
||||||
|
- type: textarea
|
||||||
|
id: logs
|
||||||
|
attributes:
|
||||||
|
label: Relevant Log Output
|
||||||
|
description: "Please copy and paste any relevant log output. This will be automatically formatted into a code block."
|
||||||
|
render: shell
|
||||||
|
|
||||||
|
- type: dropdown
|
||||||
|
id: environment
|
||||||
|
attributes:
|
||||||
|
label: Operating System
|
||||||
|
description: What operating system are you running the Docker client on?
|
||||||
|
options:
|
||||||
|
- Windows (via WSL2)
|
||||||
|
- Windows (via Docker Desktop)
|
||||||
|
- macOS (Intel)
|
||||||
|
- macOS (Apple Silicon)
|
||||||
|
- Linux
|
||||||
|
validations:
|
||||||
|
required: true
|
||||||
|
|
||||||
|
- type: checkboxes
|
||||||
|
id: no-duplicate-issues
|
||||||
|
attributes:
|
||||||
|
label: Sanity Checks
|
||||||
|
description: "Before submitting, please confirm the following:"
|
||||||
|
options:
|
||||||
|
- label: I have searched the existing issues and this is not a duplicate.
|
||||||
|
required: true
|
||||||
|
- label: I have confirmed that my `GEMINI_API_KEY` is set correctly.
|
||||||
|
required: true
|
||||||
11
.github/ISSUE_TEMPLATE/config.yml
vendored
Normal file
11
.github/ISSUE_TEMPLATE/config.yml
vendored
Normal file
@@ -0,0 +1,11 @@
|
|||||||
|
blank_issues_enabled: false
|
||||||
|
contact_links:
|
||||||
|
- name: 💬 General Discussion
|
||||||
|
url: https://github.com/BeehiveInnovations/gemini-mcp-server/discussions
|
||||||
|
about: Ask questions, share ideas, or discuss usage patterns with the community
|
||||||
|
- name: 📚 Documentation
|
||||||
|
url: https://github.com/BeehiveInnovations/gemini-mcp-server/blob/main/README.md
|
||||||
|
about: Check the README for setup instructions and usage examples
|
||||||
|
- name: 🤝 Contributing Guide
|
||||||
|
url: https://github.com/BeehiveInnovations/gemini-mcp-server/blob/main/CONTRIBUTING.md
|
||||||
|
about: Learn how to contribute to the project
|
||||||
67
.github/ISSUE_TEMPLATE/documentation.yml
vendored
Normal file
67
.github/ISSUE_TEMPLATE/documentation.yml
vendored
Normal file
@@ -0,0 +1,67 @@
|
|||||||
|
name: 📖 Documentation Improvement
|
||||||
|
description: Report an issue or suggest an improvement for the documentation
|
||||||
|
labels: ["documentation", "good first issue"]
|
||||||
|
body:
|
||||||
|
- type: input
|
||||||
|
id: location
|
||||||
|
attributes:
|
||||||
|
label: Documentation Location
|
||||||
|
description: "Which file or page has the issue? (e.g., README.md, CONTRIBUTING.md, CLAUDE.md)"
|
||||||
|
placeholder: "e.g., README.md"
|
||||||
|
validations:
|
||||||
|
required: true
|
||||||
|
|
||||||
|
- type: dropdown
|
||||||
|
id: issue-type
|
||||||
|
attributes:
|
||||||
|
label: Type of Documentation Issue
|
||||||
|
description: What kind of documentation improvement is this?
|
||||||
|
options:
|
||||||
|
- Typo or grammar error
|
||||||
|
- Unclear or confusing explanation
|
||||||
|
- Outdated information
|
||||||
|
- Missing information
|
||||||
|
- Code example doesn't work
|
||||||
|
- Installation/setup instructions unclear
|
||||||
|
- Tool usage examples need improvement
|
||||||
|
- Other
|
||||||
|
validations:
|
||||||
|
required: true
|
||||||
|
|
||||||
|
- type: textarea
|
||||||
|
id: problem
|
||||||
|
attributes:
|
||||||
|
label: What is wrong with the documentation?
|
||||||
|
description: "Please describe the problem. Be specific about what is unclear, incorrect, or missing."
|
||||||
|
placeholder: "The Docker setup command in the README is missing the `--pull=always` flag, which means users might use an outdated image version."
|
||||||
|
validations:
|
||||||
|
required: true
|
||||||
|
|
||||||
|
- type: textarea
|
||||||
|
id: suggestion
|
||||||
|
attributes:
|
||||||
|
label: Suggested Improvement
|
||||||
|
description: "How can we make it better? If you can, please provide the exact text or changes you'd like to see."
|
||||||
|
placeholder: |
|
||||||
|
Change:
|
||||||
|
```
|
||||||
|
docker run ghcr.io/beehiveinnovations/gemini-mcp-server:latest
|
||||||
|
```
|
||||||
|
|
||||||
|
To:
|
||||||
|
```
|
||||||
|
docker run --pull=always ghcr.io/beehiveinnovations/gemini-mcp-server:latest
|
||||||
|
```
|
||||||
|
|
||||||
|
- type: dropdown
|
||||||
|
id: audience
|
||||||
|
attributes:
|
||||||
|
label: Target Audience
|
||||||
|
description: Which audience would benefit most from this improvement?
|
||||||
|
options:
|
||||||
|
- New users (first-time setup)
|
||||||
|
- Developers (contributing to the project)
|
||||||
|
- Advanced users (complex workflows)
|
||||||
|
- All users
|
||||||
|
validations:
|
||||||
|
required: true
|
||||||
51
.github/ISSUE_TEMPLATE/feature_request.yml
vendored
Normal file
51
.github/ISSUE_TEMPLATE/feature_request.yml
vendored
Normal file
@@ -0,0 +1,51 @@
|
|||||||
|
name: ✨ Feature Request
|
||||||
|
description: Suggest an idea for this project
|
||||||
|
labels: ["enhancement", "needs-triage"]
|
||||||
|
body:
|
||||||
|
- type: textarea
|
||||||
|
id: problem-description
|
||||||
|
attributes:
|
||||||
|
label: What problem is this feature trying to solve?
|
||||||
|
description: "A clear and concise description of the problem or user need. Why is this change needed?"
|
||||||
|
placeholder: "Currently, I can only use one Gemini tool at a time. I want to be able to chain multiple tools together (e.g., analyze -> codereview -> thinkdeep) in a single workflow."
|
||||||
|
validations:
|
||||||
|
required: true
|
||||||
|
|
||||||
|
- type: textarea
|
||||||
|
id: proposed-solution
|
||||||
|
attributes:
|
||||||
|
label: Describe the solution you'd like
|
||||||
|
description: A clear and concise description of what you want to happen. How would it work from a user's perspective?
|
||||||
|
placeholder: "I'd like to be able to specify a workflow like 'analyze src/ then codereview the findings then use thinkdeep to suggest improvements' in a single command or configuration."
|
||||||
|
validations:
|
||||||
|
required: true
|
||||||
|
|
||||||
|
- type: textarea
|
||||||
|
id: alternatives
|
||||||
|
attributes:
|
||||||
|
label: Describe alternatives you've considered
|
||||||
|
description: A clear and concise description of any alternative solutions or features you've considered.
|
||||||
|
placeholder: "I considered manually running each tool sequentially, but automatic workflow chaining would be more efficient and ensure context is preserved between steps."
|
||||||
|
|
||||||
|
- type: dropdown
|
||||||
|
id: feature-type
|
||||||
|
attributes:
|
||||||
|
label: Feature Category
|
||||||
|
description: What type of enhancement is this?
|
||||||
|
options:
|
||||||
|
- New Gemini tool (chat, codereview, debug, etc.)
|
||||||
|
- Workflow improvement
|
||||||
|
- Integration enhancement
|
||||||
|
- Performance optimization
|
||||||
|
- User experience improvement
|
||||||
|
- Documentation enhancement
|
||||||
|
- Other
|
||||||
|
validations:
|
||||||
|
required: true
|
||||||
|
|
||||||
|
- type: checkboxes
|
||||||
|
id: contribution
|
||||||
|
attributes:
|
||||||
|
label: Contribution
|
||||||
|
options:
|
||||||
|
- label: I am willing to submit a Pull Request to implement this feature.
|
||||||
74
.github/ISSUE_TEMPLATE/tool_addition.yml
vendored
Normal file
74
.github/ISSUE_TEMPLATE/tool_addition.yml
vendored
Normal file
@@ -0,0 +1,74 @@
|
|||||||
|
name: 🛠️ New Gemini Tool Proposal
|
||||||
|
description: Propose a new Gemini MCP tool (e.g., `summarize`, `testgen`, `refactor`)
|
||||||
|
labels: ["enhancement", "new-tool"]
|
||||||
|
body:
|
||||||
|
- type: input
|
||||||
|
id: tool-name
|
||||||
|
attributes:
|
||||||
|
label: Proposed Tool Name
|
||||||
|
description: "What would the tool be called? (e.g., `summarize`, `testgen`, `refactor`)"
|
||||||
|
placeholder: "e.g., `docgen`"
|
||||||
|
validations:
|
||||||
|
required: true
|
||||||
|
|
||||||
|
- type: textarea
|
||||||
|
id: purpose
|
||||||
|
attributes:
|
||||||
|
label: What is the primary purpose of this tool?
|
||||||
|
description: "Explain the tool's core function and the value it provides to developers using Claude + Gemini."
|
||||||
|
placeholder: "This tool will automatically generate comprehensive documentation from code, extracting class and function signatures, docstrings, and creating usage examples."
|
||||||
|
validations:
|
||||||
|
required: true
|
||||||
|
|
||||||
|
- type: textarea
|
||||||
|
id: example-usage
|
||||||
|
attributes:
|
||||||
|
label: Example Usage in Claude Desktop
|
||||||
|
description: "Show how a user would invoke this tool through Claude and what the expected output would look like."
|
||||||
|
placeholder: |
|
||||||
|
**User prompt to Claude:**
|
||||||
|
"Use gemini to generate documentation for my entire src/ directory"
|
||||||
|
|
||||||
|
**Expected Gemini tool behavior:**
|
||||||
|
- Analyze all Python files in src/
|
||||||
|
- Extract classes, functions, and their docstrings
|
||||||
|
- Generate structured markdown documentation
|
||||||
|
- Include usage examples where possible
|
||||||
|
- Return organized documentation with table of contents
|
||||||
|
render: markdown
|
||||||
|
validations:
|
||||||
|
required: true
|
||||||
|
|
||||||
|
- type: dropdown
|
||||||
|
id: tool-category
|
||||||
|
attributes:
|
||||||
|
label: Tool Category
|
||||||
|
description: What category does this tool fit into?
|
||||||
|
options:
|
||||||
|
- Code Analysis (like analyze)
|
||||||
|
- Code Quality (like codereview)
|
||||||
|
- Code Generation/Refactoring
|
||||||
|
- Documentation Generation
|
||||||
|
- Testing Support
|
||||||
|
- Debugging Support (like debug)
|
||||||
|
- Workflow Automation
|
||||||
|
- Architecture Planning (like thinkdeep)
|
||||||
|
- Other
|
||||||
|
validations:
|
||||||
|
required: true
|
||||||
|
|
||||||
|
- type: textarea
|
||||||
|
id: system-prompt
|
||||||
|
attributes:
|
||||||
|
label: Proposed System Prompt (Optional)
|
||||||
|
description: "If you have ideas for how Gemini should be prompted for this tool, share them here."
|
||||||
|
placeholder: |
|
||||||
|
You are an expert technical documentation generator. Your task is to create comprehensive, user-friendly documentation from source code...
|
||||||
|
|
||||||
|
- type: checkboxes
|
||||||
|
id: contribution
|
||||||
|
attributes:
|
||||||
|
label: Contribution
|
||||||
|
options:
|
||||||
|
- label: I am willing to submit a Pull Request to implement this new tool.
|
||||||
|
- label: I have checked that this tool doesn't overlap significantly with existing tools (analyze, codereview, debug, thinkdeep, chat).
|
||||||
116
.github/pull_request_template.md
vendored
Normal file
116
.github/pull_request_template.md
vendored
Normal file
@@ -0,0 +1,116 @@
|
|||||||
|
<!--
|
||||||
|
Thank you for your contribution to the Gemini MCP Server!
|
||||||
|
Please provide a clear description of your changes and ensure all requirements are met.
|
||||||
|
-->
|
||||||
|
|
||||||
|
## Related Issue
|
||||||
|
|
||||||
|
<!-- Link to the issue that this PR addresses -->
|
||||||
|
<!-- e.g., "Closes #123" or "Fixes #456" -->
|
||||||
|
<!-- If no issue exists, please consider creating one first to discuss the change -->
|
||||||
|
|
||||||
|
Closes #
|
||||||
|
|
||||||
|
## Type of Change
|
||||||
|
|
||||||
|
<!--
|
||||||
|
Please check the relevant box with [x]
|
||||||
|
-->
|
||||||
|
|
||||||
|
- [ ] 🐞 Bug fix (non-breaking change which fixes an issue)
|
||||||
|
- [ ] ✨ New feature (non-breaking change which adds functionality)
|
||||||
|
- [ ] 🛠️ New Gemini tool (adds a new tool like `chat`, `codereview`, etc.)
|
||||||
|
- [ ] 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
|
||||||
|
- [ ] 📖 Documentation update
|
||||||
|
- [ ] 🧹 Refactor or chore (no user-facing changes)
|
||||||
|
- [ ] 🏗️ Infrastructure/CI changes
|
||||||
|
|
||||||
|
## Description
|
||||||
|
|
||||||
|
<!--
|
||||||
|
A clear and concise description of the changes.
|
||||||
|
- **What** is the change?
|
||||||
|
- **Why** is this change necessary?
|
||||||
|
- **How** does it address the issue?
|
||||||
|
-->
|
||||||
|
|
||||||
|
## Testing
|
||||||
|
|
||||||
|
<!--
|
||||||
|
The project has high testing standards. Please describe the tests you have added or updated.
|
||||||
|
Both unit tests (no API key) and live integration tests (with API key) are important.
|
||||||
|
-->
|
||||||
|
|
||||||
|
### Unit Tests (Required)
|
||||||
|
- [ ] I have added new unit tests to cover my changes
|
||||||
|
- [ ] I have run `python -m pytest tests/ --ignore=tests/test_live_integration.py -v` and all tests pass
|
||||||
|
- [ ] New tests use proper mocking and don't require API keys
|
||||||
|
|
||||||
|
### Live Integration Tests (Recommended)
|
||||||
|
- [ ] I have tested this with a real Gemini API key using `python tests/test_live_integration.py`
|
||||||
|
- [ ] The changes work as expected with actual API calls
|
||||||
|
- [ ] I have tested this on [macOS/Linux/Windows (WSL2)]
|
||||||
|
|
||||||
|
### Docker Testing (If Applicable)
|
||||||
|
- [ ] I have tested the Docker build: `docker build -t test-image .`
|
||||||
|
- [ ] I have tested the Docker functionality: `./setup-docker.sh`
|
||||||
|
- [ ] Docker integration works with the changes
|
||||||
|
|
||||||
|
## Code Quality
|
||||||
|
|
||||||
|
<!--
|
||||||
|
Please confirm you've followed the project's quality standards
|
||||||
|
-->
|
||||||
|
|
||||||
|
- [ ] My code follows the project's style guidelines (`black .` and `ruff check .`)
|
||||||
|
- [ ] I have run the linting tools and fixed any issues
|
||||||
|
- [ ] I have commented my code, particularly in hard-to-understand areas
|
||||||
|
- [ ] My changes generate no new warnings
|
||||||
|
- [ ] I have updated type hints where applicable
|
||||||
|
|
||||||
|
## Documentation
|
||||||
|
|
||||||
|
<!--
|
||||||
|
Documentation should be updated to reflect any user-facing changes
|
||||||
|
-->
|
||||||
|
|
||||||
|
- [ ] I have made corresponding changes to the documentation
|
||||||
|
- [ ] I have updated the README.md if my changes affect usage
|
||||||
|
- [ ] I have updated CONTRIBUTING.md if my changes affect the development workflow
|
||||||
|
- [ ] For new tools: I have added usage examples and parameter documentation
|
||||||
|
|
||||||
|
## Breaking Changes
|
||||||
|
|
||||||
|
<!--
|
||||||
|
If this is a breaking change, please describe what breaks and how users should adapt
|
||||||
|
-->
|
||||||
|
|
||||||
|
- [ ] This change is backwards compatible
|
||||||
|
- [ ] OR: I have documented the breaking changes and migration path below
|
||||||
|
|
||||||
|
<!--
|
||||||
|
If breaking changes, describe them here:
|
||||||
|
-->
|
||||||
|
|
||||||
|
## Additional Context
|
||||||
|
|
||||||
|
<!--
|
||||||
|
Add any other context about the pull request here, such as:
|
||||||
|
- Performance implications
|
||||||
|
- Security considerations
|
||||||
|
- Future improvements this enables
|
||||||
|
- Screenshots (for UI changes)
|
||||||
|
- Related PRs or issues
|
||||||
|
-->
|
||||||
|
|
||||||
|
## Checklist for Maintainers
|
||||||
|
|
||||||
|
<!--
|
||||||
|
This section is for maintainers to check during review
|
||||||
|
-->
|
||||||
|
|
||||||
|
- [ ] Code review completed
|
||||||
|
- [ ] All CI checks passing
|
||||||
|
- [ ] Breaking changes properly documented
|
||||||
|
- [ ] Version bump needed (if applicable)
|
||||||
|
- [ ] Documentation updated and accurate
|
||||||
77
.github/workflows/build_and_publish_docker.yml
vendored
Normal file
77
.github/workflows/build_and_publish_docker.yml
vendored
Normal file
@@ -0,0 +1,77 @@
|
|||||||
|
name: Build and Publish Docker Image to GHCR
|
||||||
|
|
||||||
|
on:
|
||||||
|
push:
|
||||||
|
branches: [ main ]
|
||||||
|
tags: [ 'v*' ]
|
||||||
|
pull_request:
|
||||||
|
branches: [ main ]
|
||||||
|
|
||||||
|
env:
|
||||||
|
REGISTRY: ghcr.io
|
||||||
|
IMAGE_NAME: ${{ github.repository }}
|
||||||
|
|
||||||
|
jobs:
|
||||||
|
build-and-push:
|
||||||
|
runs-on: ubuntu-latest
|
||||||
|
permissions:
|
||||||
|
contents: read
|
||||||
|
packages: write
|
||||||
|
id-token: write
|
||||||
|
|
||||||
|
steps:
|
||||||
|
- name: Checkout repository
|
||||||
|
uses: actions/checkout@v4
|
||||||
|
|
||||||
|
- name: Set up Docker Buildx
|
||||||
|
uses: docker/setup-buildx-action@v3
|
||||||
|
|
||||||
|
- name: Log in to GitHub Container Registry
|
||||||
|
if: github.event_name != 'pull_request'
|
||||||
|
uses: docker/login-action@v3
|
||||||
|
with:
|
||||||
|
registry: ${{ env.REGISTRY }}
|
||||||
|
username: ${{ github.actor }}
|
||||||
|
password: ${{ secrets.GITHUB_TOKEN }}
|
||||||
|
|
||||||
|
- name: Extract metadata (tags, labels) for Docker
|
||||||
|
id: meta
|
||||||
|
uses: docker/metadata-action@v5
|
||||||
|
with:
|
||||||
|
images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
|
||||||
|
tags: |
|
||||||
|
type=ref,event=branch
|
||||||
|
type=ref,event=pr
|
||||||
|
type=ref,event=tag
|
||||||
|
type=sha,prefix={{branch}}-
|
||||||
|
type=raw,value=latest,enable={{is_default_branch}}
|
||||||
|
|
||||||
|
- name: Build Docker image for PR
|
||||||
|
if: github.event_name == 'pull_request'
|
||||||
|
uses: docker/build-push-action@v5
|
||||||
|
with:
|
||||||
|
context: .
|
||||||
|
push: false
|
||||||
|
tags: ${{ steps.meta.outputs.tags }}
|
||||||
|
labels: ${{ steps.meta.outputs.labels }}
|
||||||
|
cache-from: type=gha
|
||||||
|
cache-to: type=gha,mode=max
|
||||||
|
|
||||||
|
- name: Build and push Docker image
|
||||||
|
if: github.event_name != 'pull_request'
|
||||||
|
uses: docker/build-push-action@v5
|
||||||
|
with:
|
||||||
|
context: .
|
||||||
|
push: true
|
||||||
|
tags: ${{ steps.meta.outputs.tags }}
|
||||||
|
labels: ${{ steps.meta.outputs.labels }}
|
||||||
|
cache-from: type=gha
|
||||||
|
cache-to: type=gha,mode=max
|
||||||
|
|
||||||
|
- name: Generate artifact attestation
|
||||||
|
if: github.event_name != 'pull_request'
|
||||||
|
uses: actions/attest-build-provenance@v1
|
||||||
|
with:
|
||||||
|
subject-name: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME}}
|
||||||
|
subject-digest: ${{ steps.build.outputs.digest }}
|
||||||
|
push-to-registry: true
|
||||||
12
.gitignore
vendored
12
.gitignore
vendored
@@ -158,4 +158,14 @@ test_output/
|
|||||||
.coverage
|
.coverage
|
||||||
htmlcov/
|
htmlcov/
|
||||||
coverage.xml
|
coverage.xml
|
||||||
.pytest_cache/
|
.pytest_cache/
|
||||||
|
|
||||||
|
# Additional files
|
||||||
|
run-gemini-mcp.sh
|
||||||
|
gemini-repo.md
|
||||||
|
.mcp.json
|
||||||
|
.claude
|
||||||
|
CLAUDE.md
|
||||||
|
|
||||||
|
# Memory Bank (optional - can be committed for shared context)
|
||||||
|
memory-bank
|
||||||
246
docs/docker-user-guide.md
Normal file
246
docs/docker-user-guide.md
Normal file
@@ -0,0 +1,246 @@
|
|||||||
|
# 🐳 Docker User Guide: Using Gemini MCP Server
|
||||||
|
|
||||||
|
This guide is for users who want to use the Gemini MCP Server with Claude Desktop **without cloning the repository**. You'll use the pre-built Docker image published to GitHub Container Registry.
|
||||||
|
|
||||||
|
## 🎯 What You'll Get
|
||||||
|
|
||||||
|
After following this guide, you'll have:
|
||||||
|
- ✅ Gemini MCP Server running with Claude Desktop
|
||||||
|
- ✅ Access to all Gemini tools: `chat`, `thinkdeep`, `codereview`, `debug`, `analyze`, `precommit`
|
||||||
|
- ✅ Automatic conversation threading between Claude and Gemini
|
||||||
|
- ✅ No need to manage Python dependencies or clone code
|
||||||
|
|
||||||
|
## 📋 Prerequisites
|
||||||
|
|
||||||
|
### Required
|
||||||
|
1. **Docker Desktop** - [Download here](https://www.docker.com/products/docker-desktop/)
|
||||||
|
2. **Claude Desktop** - [Download here](https://claude.ai/download)
|
||||||
|
3. **Gemini API Key** - [Get one here](https://makersuite.google.com/app/apikey)
|
||||||
|
|
||||||
|
### Platform Support
|
||||||
|
- ✅ **macOS** (Intel and Apple Silicon)
|
||||||
|
- ✅ **Linux**
|
||||||
|
- ✅ **Windows** (requires WSL2 for Claude Desktop)
|
||||||
|
|
||||||
|
## 🚀 Quick Setup (5 minutes)
|
||||||
|
|
||||||
|
### Step 1: Start Redis (Required for AI Conversations)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Start Redis for conversation threading
|
||||||
|
docker run -d \
|
||||||
|
--name gemini-redis \
|
||||||
|
--restart unless-stopped \
|
||||||
|
-p 6379:6379 \
|
||||||
|
redis:latest
|
||||||
|
```
|
||||||
|
|
||||||
|
This creates a persistent Redis container that will survive system restarts.
|
||||||
|
|
||||||
|
### Step 2: Start Gemini MCP Server
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Create and start the MCP server
|
||||||
|
docker run -d \
|
||||||
|
--name gemini-mcp-server \
|
||||||
|
--restart unless-stopped \
|
||||||
|
--network host \
|
||||||
|
-e GEMINI_API_KEY="your-gemini-api-key-here" \
|
||||||
|
-e REDIS_URL="redis://localhost:6379/0" \
|
||||||
|
-v "$(pwd):/workspace" \
|
||||||
|
ghcr.io/beehiveinnovations/gemini-mcp-server:latest
|
||||||
|
```
|
||||||
|
|
||||||
|
**Replace `your-gemini-api-key-here` with your actual API key.**
|
||||||
|
|
||||||
|
**Command explained:**
|
||||||
|
- `-d`: Run in background
|
||||||
|
- `--restart unless-stopped`: Auto-restart container
|
||||||
|
- `--network host`: Connect to your local Redis
|
||||||
|
- `-e`: Set environment variables
|
||||||
|
- `-v "$(pwd):/workspace"`: Mount current directory for file access
|
||||||
|
- `ghcr.io/beehiveinnovations/gemini-mcp-server:latest`: The published image
|
||||||
|
|
||||||
|
### Step 3: Configure Claude Desktop
|
||||||
|
|
||||||
|
Find your Claude Desktop config file:
|
||||||
|
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
|
||||||
|
- **Windows (WSL)**: `/mnt/c/Users/USERNAME/AppData/Roaming/Claude/claude_desktop_config.json`
|
||||||
|
|
||||||
|
Add this configuration:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"gemini": {
|
||||||
|
"command": "docker",
|
||||||
|
"args": [
|
||||||
|
"exec",
|
||||||
|
"-i",
|
||||||
|
"gemini-mcp-server",
|
||||||
|
"python",
|
||||||
|
"server.py"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 4: Restart Claude Desktop
|
||||||
|
|
||||||
|
Completely quit and restart Claude Desktop for changes to take effect.
|
||||||
|
|
||||||
|
### Step 5: Test It Works
|
||||||
|
|
||||||
|
Open Claude Desktop and try:
|
||||||
|
```
|
||||||
|
"Use gemini to chat about Python best practices"
|
||||||
|
```
|
||||||
|
|
||||||
|
You should see Gemini respond through Claude!
|
||||||
|
|
||||||
|
## 🛠️ Available Tools
|
||||||
|
|
||||||
|
Once set up, you can use any of these tools naturally in Claude:
|
||||||
|
|
||||||
|
| Tool | Example Usage |
|
||||||
|
|------|---------------|
|
||||||
|
| **`chat`** | "Use gemini to brainstorm API design ideas" |
|
||||||
|
| **`thinkdeep`** | "Use gemini to think deeper about this architecture" |
|
||||||
|
| **`codereview`** | "Use gemini to review my Python code for security issues" |
|
||||||
|
| **`debug`** | "Use gemini to debug this error: [paste stack trace]" |
|
||||||
|
| **`analyze`** | "Use gemini to analyze my project structure" |
|
||||||
|
| **`precommit`** | "Use gemini to validate my git changes before commit" |
|
||||||
|
|
||||||
|
## 📁 File Access
|
||||||
|
|
||||||
|
The Docker setup automatically mounts your current directory as `/workspace`. This means:
|
||||||
|
|
||||||
|
- ✅ Gemini can read files in your current directory and subdirectories
|
||||||
|
- ✅ You can analyze entire projects: "Use gemini to analyze my src/ directory"
|
||||||
|
- ✅ Works with relative paths: "Use gemini to review ./main.py"
|
||||||
|
|
||||||
|
## 🔧 Management Commands
|
||||||
|
|
||||||
|
### Check Status
|
||||||
|
```bash
|
||||||
|
# See if containers are running
|
||||||
|
docker ps
|
||||||
|
|
||||||
|
# Should show both 'gemini-redis' and 'gemini-mcp-server'
|
||||||
|
```
|
||||||
|
|
||||||
|
### View Logs
|
||||||
|
```bash
|
||||||
|
# Check MCP server logs
|
||||||
|
docker logs gemini-mcp-server
|
||||||
|
|
||||||
|
# Follow logs in real-time
|
||||||
|
docker logs -f gemini-mcp-server
|
||||||
|
```
|
||||||
|
|
||||||
|
### Update to Latest Version
|
||||||
|
```bash
|
||||||
|
# Stop current container
|
||||||
|
docker stop gemini-mcp-server
|
||||||
|
docker rm gemini-mcp-server
|
||||||
|
|
||||||
|
# Pull latest image and restart (repeat Step 2)
|
||||||
|
docker pull ghcr.io/beehiveinnovations/gemini-mcp-server:latest
|
||||||
|
# Then run the docker run command from Step 2
|
||||||
|
```
|
||||||
|
|
||||||
|
### Stop Everything
|
||||||
|
```bash
|
||||||
|
# Stop containers (keeps Redis data)
|
||||||
|
docker stop gemini-mcp-server gemini-redis
|
||||||
|
|
||||||
|
# Or remove everything completely
|
||||||
|
docker stop gemini-mcp-server gemini-redis
|
||||||
|
docker rm gemini-mcp-server gemini-redis
|
||||||
|
```
|
||||||
|
|
||||||
|
## 🔒 Security Notes
|
||||||
|
|
||||||
|
1. **API Key**: Your Gemini API key is stored in the Docker container environment. Use a dedicated key for this purpose.
|
||||||
|
|
||||||
|
2. **File Access**: The container can read files in your mounted directory. Don't mount sensitive directories unnecessarily.
|
||||||
|
|
||||||
|
3. **Network**: The container uses host networking to connect to Redis. This is safe for local development.
|
||||||
|
|
||||||
|
## 🚨 Troubleshooting
|
||||||
|
|
||||||
|
### "Connection failed" in Claude Desktop
|
||||||
|
```bash
|
||||||
|
# Check if containers are running
|
||||||
|
docker ps
|
||||||
|
|
||||||
|
# Restart MCP server if needed
|
||||||
|
docker restart gemini-mcp-server
|
||||||
|
|
||||||
|
# Check logs for errors
|
||||||
|
docker logs gemini-mcp-server
|
||||||
|
```
|
||||||
|
|
||||||
|
### "GEMINI_API_KEY environment variable is required"
|
||||||
|
```bash
|
||||||
|
# Stop and recreate container with correct API key
|
||||||
|
docker stop gemini-mcp-server
|
||||||
|
docker rm gemini-mcp-server
|
||||||
|
# Then run Step 2 again with the correct API key
|
||||||
|
```
|
||||||
|
|
||||||
|
### "Redis connection failed"
|
||||||
|
```bash
|
||||||
|
# Check if Redis is running
|
||||||
|
docker ps | grep redis
|
||||||
|
|
||||||
|
# Start Redis if stopped
|
||||||
|
docker start gemini-redis
|
||||||
|
|
||||||
|
# Or recreate Redis
|
||||||
|
docker rm -f gemini-redis
|
||||||
|
# Then run Step 1 again
|
||||||
|
```
|
||||||
|
|
||||||
|
### Tools not responding / hanging
|
||||||
|
```bash
|
||||||
|
# Check for resource constraints
|
||||||
|
docker stats
|
||||||
|
|
||||||
|
# Restart everything
|
||||||
|
docker restart gemini-redis gemini-mcp-server
|
||||||
|
```
|
||||||
|
|
||||||
|
### Windows WSL2 Issues
|
||||||
|
- Ensure Docker Desktop is set to use WSL2 backend
|
||||||
|
- Run commands from within WSL2, not Windows Command Prompt
|
||||||
|
- Use WSL2 paths for file mounting
|
||||||
|
|
||||||
|
## 🎉 What's Next?
|
||||||
|
|
||||||
|
Once you're set up:
|
||||||
|
|
||||||
|
1. **Explore the tools**: Try each tool to understand their specialties
|
||||||
|
2. **Read the main README**: [Full documentation](../README.md) has advanced usage patterns
|
||||||
|
3. **Join discussions**: [GitHub Discussions](https://github.com/BeehiveInnovations/gemini-mcp-server/discussions) for tips and tricks
|
||||||
|
4. **Contribute**: Found a bug or want a feature? [Open an issue](https://github.com/BeehiveInnovations/gemini-mcp-server/issues)
|
||||||
|
|
||||||
|
## 💡 Pro Tips
|
||||||
|
|
||||||
|
1. **Conversation Threading**: Gemini remembers context across multiple interactions - you can have extended conversations!
|
||||||
|
|
||||||
|
2. **File Analysis**: Point Gemini at entire directories: "Use gemini to analyze my entire project for architectural improvements"
|
||||||
|
|
||||||
|
3. **Collaborative Workflows**: Combine tools: "Use gemini to analyze this code, then review it for security issues"
|
||||||
|
|
||||||
|
4. **Thinking Modes**: Control depth vs cost: "Use gemini with minimal thinking to quickly explain this function"
|
||||||
|
|
||||||
|
5. **Web Search**: Enable web search for current info: "Use gemini to debug this React error with web search enabled"
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Need Help?**
|
||||||
|
- 📖 [Full Documentation](../README.md)
|
||||||
|
- 💬 [Community Discussions](https://github.com/BeehiveInnovations/gemini-mcp-server/discussions)
|
||||||
|
- 🐛 [Report Issues](https://github.com/BeehiveInnovations/gemini-mcp-server/issues)
|
||||||
Reference in New Issue
Block a user