🎯 Overview

GitPasha MCP Server is a Model Context Protocol (MCP) server that enables Claude Desktop to interact with GitPasha repositories. It provides a comprehensive set of tools for repository management, issue tracking, and pull request operations.

Key Capabilities:

• 🔐 Secure API authentication
• 📦 Repository CRUD operations
• 🐛 Issue management
• 🔀 Pull request creation
• 📝 README file generation
• 🌐 Both local (stdio) and cloud (SSE) deployment

---

✨ Features

• ✅ Repository Management: Create, update, delete repositories
• ✅ Issue Tracking: List, create, update issues with labels and assignees
• ✅ Pull Requests: Open pull requests between branches
• ✅ Auto-suggestions: Smart repository descriptions
• ✅ Flexible Deployment: Local stdio or cloud SSE transport
• ✅ Docker Ready: Containerized for easy cloud deployment
• ✅ Comprehensive Logging: Detailed activity logs for debugging

---

📁 Project Structure

gitpasha-mcp/
├── 📄 main.py                    # Server entry point
├── 📄 Dockerfile                 # Docker configuration
├── 📄 requirements.txt           # Python dependencies
├── 📄 .env                       # Environment variables (create from .env.example)
├── 📄 .env.example              # Environment template
├── 📄 .gitignore                # Git ignore rules
├── 📄 .dockerignore             # Docker ignore rules
├── 📄 README.md                 # This file
│
├── 📂 api/                      # API layer - Direct GitPasha API calls
│   ├── __init__.py
│   ├── 📂 repos/                # Repository operations
│   │   ├── __init__.py
│   │   ├── create.py           # Create repository
│   │   ├── update.py           # Update repository
│   │   └── delete.py           # Delete repository
│   ├── 📂 issues/               # Issue operations
│   │   ├── __init__.py
│   │   ├── list.py             # List issues
│   │   ├── create.py           # Create issue
│   │   └── update.py           # Update issue
│   ├── 📂 pulls/                # Pull request operations
│   │   ├── __init__.py
│   │   └── open.py             # Open pull request
│   └── 📂 files/                # File operations
│       ├── __init__.py
│       └── create_readme.py    # Create README
│
├── 📂 tools/                    # Tools layer - MCP tool wrappers
│   ├── __init__.py
│   ├── repo_create.py          # Repository creation tool
│   ├── repo_update.py          # Repository update tool
│   ├── repo_delete.py          # Repository deletion tool
│   ├── issue_list.py           # Issue listing tool
│   ├── issue_create.py         # Issue creation tool
│   ├── issue_update.py         # Issue update tool
│   └── pr_open.py              # Pull request tool
│
├── 📂 helpers/                  # Helper utilities
│   ├── __init__.py
│   ├── logger.py               # Logging configuration
│   ├── headers.py              # API authentication headers
│   ├── http_client.py          # HTTP client with logging
│   ├── error_formatter.py      # Error message formatting
│   └── descriptions.py         # Repository description suggestions
│
└── 📂 logs/                     # Application logs (auto-created)
    └── gitpasha.log

---

🔧 Installation

Prerequisites:

• Python 3.12+ installed
• Git installed
• GitPasha account with API access
• Docker (optional, for cloud deployment)

Step 1: Clone the Repository

git clone https://github.com/YOUR_USERNAME/gitpasha-mcp.git
cd gitpasha-mcp

Step 2: Create Virtual Environment

# Windows
python -m venv .venv
.venv\Scripts\activate

# macOS/Linux
python3 -m venv .venv
source .venv/bin/activate

Step 3: Install Dependencies

pip install -r requirements.txt

---

⚙️ Configuration

Step 1: Create Environment File

# Copy the example file
cp .env.example .env

Step 2: Configure .env

Edit .env with your credentials:

# GitPasha API Configuration
GITPASHA_API_KEY=your_api_key_here
GITPASHA_BASE_URL=https://app.gitpasha.com/api/v1
GITPASHA__USERNAME=your_username

# Logging Configuration
LOG_LEVEL=DEBUG
LOG_FILE=logs/gitpasha.log

# Server Configuration (for cloud deployment)
MCP_TRANSPORT=stdio          # Use 'stdio' for local, 'sse' for cloud
HOST=0.0.0.0
PORT=8000

Step 3: Get Your API Key

1. Visit: https://app.gitpasha.com/settings
2. Navigate to API Keys section
3. Generate a new API key
4. Copy and paste into .env

Step 4: Create Logs Directory

mkdir logs

---

🚀 Running the Server

Local Development (stdio - for Claude Desktop)

# Set transport to stdio in .env
MCP_TRANSPORT=stdio

# Run the server
python main.py

You should see:

INFO | Starting MCP server | BASE_URL=https://app.gitpasha.com/api/v1 | Transport=stdio

Cloud Deployment (SSE - for remote access)

# Set transport to sse in .env
MCP_TRANSPORT=sse

# Run the server
python main.py

You should see:

INFO | Starting SSE server on 0.0.0.0:8000
INFO | Uvicorn running on http://0.0.0.0:8000

---

🔍 Testing with Inspector

The MCP Inspector is a debugging tool for testing your MCP server.

Step 1: Start the Inspector

npx @modelcontextprotocol/inspector

Output:

🚀 MCP Inspector is up and running at:
   http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=...

Step 2: Configure Connection

• For Local (stdio):

  • In the Inspector UI:
    • Transport: stdio
    • Command: .venv\Scripts\python.exe (Windows) or .venv/bin/python (macOS/Linux)
    • Args: main.py

• For Cloud (SSE):

  • In the Inspector UI:
    • Transport: sse
    • URL: http://localhost:8000/sse

Step 3: Test Tools

Once connected, you'll see all available tools. Try testing:

Create Repository:

{
    "name": "test-repo",
    "description": "Test repository from inspector",
    "private": false
}

List Issues:

{
    "repo": "test-repo",
    "state": "open"
}

---

🖥️ Claude Desktop Integration

Step 1: Locate Config File

Windows:

%APPDATA%\Claude\claude_desktop_config.json

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Linux:

~/.config/Claude/claude_desktop_config.json

Step 2: Add Server Configuration

For Local Development (stdio):

{
    "mcpServers": {
      "gitpasha": {
        "command": "python",
        "args": [
          "C:\\Users\\YOUR_USERNAME\\path\\to\\gitpasha-mcp\\main.py"
        ],
        "env": {
          "MCP_TRANSPORT": "stdio"
        }
      }
    }
}

For Cloud/Remote (SSE):

{
    "mcpServers": {
      "gitpasha": {
        "url": "https://your-app.ghaymah.systems/sse",
        "transport": "sse"
      }
    }
}

Step 3: Restart Claude Desktop

Close and reopen Claude Desktop completely.

Step 4: Verify Connection

In Claude Desktop, look for the 🔌 hammer icon indicating MCP servers are connected. You should see "gitpasha" listed.

---

☁️ Deployment

Docker Deployment

Build Image

docker build -t gitpasha-mcp:latest .

docker run -p 8000:8000 --env-file .env gitpasha-mcp:latest

Push to Docker Hub

# Login
docker login

# Tag
docker tag gitpasha-mcp:latest YOUR_DOCKERHUB_USERNAME/gitpasha-mcp:latest

# Push
docker push YOUR_DOCKERHUB_USERNAME/gitpasha-mcp:latest

Ghaymah Cloud Deployment

1. Visit: https://deploy.ghaymah.systems/
2. Choose: Deploy from Docker Hub or Deploy from GitHub
3. Configure Environment Variables:

   GITPASHA_API_KEY=your_api_key
   GITPASHA__USERNAME=your_username
   GITPASHA_BASE_URL=https://app.gitpasha.com/api/v1
   MCP_TRANSPORT=sse
   HOST=0.0.0.0
   PORT=8000
   

4. Deploy and get your URL!

---

🛠️ Available Tools

1. repo_create_tool

Create a new repository Parameters:

• name (required): Repository name
• description (optional): Repository description
• private (optional): Make repository private (default: false)
• create_readme (optional): Create README file (default: true)
• readme_content (optional): Custom README content

Example:

Create a new repository called "my-api-project"

2. repo_update_tool

Update repository settings

Parameters:

• repo (required): Repository name (e.g., "test-repo" or "username/test-repo")
• name (optional): New repository name
• description (optional): New description
• private (optional): Change privacy setting

Example:

Update repository "test-repo" to have description "Production API"

3. repo_delete_tool

Delete a repository

Example:

• repo (required): Repository name

Example:

Delete repository "old-test-repo"

4. issue_list_tool

List repository issues

Parameters:

• repo (required): Repository name
• state (optional): "open", "closed", or "all" (default: "open")

Example:

Show me all open issues in "my-project"

5. issue_create_tool Create a new issue

Parameters:

• repo (required): Repository name
• title (required): Issue title
• body (optional): Issue description
• labels_csv (optional): Comma-separated labels
• assignees_csv (optional): Comma-separated usernames

Example:

Create an issue in "my-project" titled "Fix login bug" with label "bug"

6. issue_update_tool

Update an existing issue

Parameters:

• repo (required): Repository name
• issue (required): Issue number
• title (optional): New title
• body (optional): New description
• state (optional): "open" or "closed"
• labels_csv (optional): Update labels
• assignees_csv (optional): Update assignees
• comment (optional): Add comment to issue

Example:

Close issue #5 in "my-project" and add comment "Fixed in PR #10"

7. pr_open_tool Open a pull request

Parameters:

• repo (required): Repository name
• title (required): PR title
• head (required): Source branch
• base (required): Target branch
• body (optional): PR description

Example:

Open a pull request in "my-project" from "feature-branch" to "main"

---

💡 Usage Examples

Example 1: Create and Initialize Project

Create a new repository called "awesome-api" with description "RESTful API for awesome app"

Claude will:

1. Create the repository
2. Generate a README file
3. Return the repository URL

Example 2: Manage Issues

List all open issues in my-project

Then:

Create a new issue in my-project titled "Add authentication" with labels "enhancement,security"

Then:

Update issue #3 in my-project, close it and add comment "Implemented in v2.0"

Example 3: Repository Workflow

Update repository "test-api" to be private and change description to "Internal API"

---

🐛 Troubleshooting

Issue: "GITPASHA__USERNAME not set in .env"

Solution: Add your username to .env:

GITPASHA__USERNAME=your_username

Issue: "Invalid or expired API key"

Solution:

1. Verify API key in .env
2. Generate new key from https://app.gitpasha.com/settings
3. Ensure no extra spaces in .env file

Issue: "404 page not found"

Solution: Make sure repository name includes username:

• Correct: "test-repo" (username added automatically)
• Correct: "username/test-repo"

Issue: Claude Desktop not connecting

Solution:

1. Check claude_desktop_config.json syntax
2. Verify file paths use correct slashes
3. Restart Claude Desktop completely
4. Check logs: logs/gitpasha.log

Issue: SSE connection fails

Solution:

1. Verify server is running on 0.0.0.0:8000
2. Check firewall settings
3. Test with:

   curl http://localhost:8000/sse
   

---

💬 contact with me:

mail: mohamedelawakey@gmail.com

whatsapp/phone : +201127247680

---