The Gitea MCP Server provides Claude Code with direct access to Gitea for issue management, label operations, and repository tracking. It supports both single-repository (project mode) and multi-repository (company/PMO mode) operations.

Status: ✅ Phase 1 Complete - Fully functional and tested

Features

Core Functionality

Issue Management: CRUD operations for Gitea issues
Label Taxonomy: Dynamic 44-label system with intelligent suggestions
Mode Detection: Automatic project vs company-wide mode detection
Branch-Aware Security: Prevents accidental changes on production branches
Hybrid Configuration: System-level credentials + project-level paths
PMO Support: Multi-repository aggregation for organization-wide views

Tools Provided (36 total)

Issue Management (6 tools)

Tool	Description	Mode
`list_issues`	List issues from repository	Both
`get_issue`	Get specific issue details	Both
`create_issue`	Create new issue with labels	Both
`update_issue`	Update existing issue	Both
`add_comment`	Add comment to issue	Both
`aggregate_issues`	Cross-repository issue aggregation	PMO Only

Label Management (5 tools)

Tool	Description	Mode
`get_labels`	Get all labels (org + repo)	Both
`suggest_labels`	Intelligent label suggestion	Both
`create_label`	Create repo-level label	Both
`create_org_label`	Create organization-level label	Both
`create_label_smart`	Auto-detect org vs repo for label creation	Both

Wiki & Lessons Learned (7 tools)

Tool	Description	Mode
`list_wiki_pages`	List all wiki pages	Both
`get_wiki_page`	Get specific wiki page content	Both
`create_wiki_page`	Create new wiki page	Both
`update_wiki_page`	Update existing wiki page	Both
`create_lesson`	Create lessons learned entry	Both
`search_lessons`	Search lessons by query/tags	Both
`allocate_rfc_number`	Get next available RFC number	Both

Milestone Management (5 tools)

Tool	Description	Mode
`list_milestones`	List all milestones	Both
`get_milestone`	Get specific milestone	Both
`create_milestone`	Create new milestone	Both
`update_milestone`	Update existing milestone	Both
`delete_milestone`	Delete a milestone	Both

Issue Dependencies (4 tools)

Tool	Description	Mode
`list_issue_dependencies`	List blocking issues	Both
`create_issue_dependency`	Create dependency between issues	Both
`remove_issue_dependency`	Remove dependency	Both
`get_execution_order`	Calculate parallelizable execution order	Both

Pull Request Tools (7 tools)

Tool	Description	Mode
`list_pull_requests`	List PRs from repository	Both
`get_pull_request`	Get specific PR details	Both
`get_pr_diff`	Get PR diff content	Both
`get_pr_comments`	Get comments on a PR	Both
`create_pr_review`	Create PR review (approve/request changes)	Both
`add_pr_comment`	Add comment to PR	Both
`create_pull_request`	Create new pull request	Both

Validation Tools (2 tools)

Tool	Description	Mode
`validate_repo_org`	Check if repo belongs to organization	Both
`get_branch_protection`	Get branch protection rules	Both

Architecture

Directory Structure

mcp-servers/gitea/
├── .venv/                      # Python virtual environment
├── requirements.txt            # Python dependencies
├── run.sh                      # Entry point script
├── mcp_server/
│   ├── __init__.py
│   ├── server.py              # MCP server entry point (36 tools)
│   ├── config.py              # Configuration loader with auto-detection
│   ├── gitea_client.py        # Gitea API client
│   └── tools/
│       ├── __init__.py
│       ├── issues.py          # Issue management tools
│       ├── labels.py          # Label management tools
│       ├── wiki.py            # Wiki & lessons learned tools
│       ├── milestones.py      # Milestone management tools
│       ├── dependencies.py    # Issue dependency tools
│       └── pull_requests.py   # Pull request tools
├── tests/
│   ├── __init__.py
│   ├── test_config.py
│   ├── test_gitea_client.py
│   ├── test_issues.py
│   └── test_labels.py
├── README.md                   # This file
├── TESTING.md                  # Testing instructions
└── CHANGELOG.md                # Version history

Mode Detection

The server operates in two modes based on environment variables:

Project Mode (Single Repository):

When GITEA_REPO is set
Operates on single repository
Used by projman plugin

Company Mode (Multi-Repository / PMO):

When GITEA_REPO is NOT set
Operates on all repositories in organization
Used by projman-pmo plugin

Branch-Aware Security

Operations are restricted based on the current Git branch:

Branch	Read	Create Issue	Update/Comment
`main`, `master`, `prod/*`	✅	❌	❌
`staging`, `stage/*`	✅	✅	❌
`development`, `develop`, `feat/`, `dev/`	✅	✅	✅

Installation

Prerequisites

Python 3.10 or higher
Git repository (for branch detection)
Access to Gitea instance with API token

Step 1: Install Dependencies

cd mcp-servers/gitea
python3 -m venv .venv
source .venv/bin/activate  # Linux/Mac
# or .venv\Scripts\activate  # Windows
pip install -r requirements.txt

Step 2: Configure System-Level Settings

Create ~/.config/claude/gitea.env:

mkdir -p ~/.config/claude

cat > ~/.config/claude/gitea.env << EOF
GITEA_API_URL=https://gitea.example.com/api/v1
GITEA_API_TOKEN=your_gitea_token_here
EOF

chmod 600 ~/.config/claude/gitea.env

Step 3: Configure Project-Level Settings (Optional)

For project mode, create .env in your project root:

echo "GITEA_REPO=your-repo-name" > .env
echo ".env" >> .gitignore

For company/PMO mode, omit the .env file or don't set GITEA_REPO.

Configuration

System-Level Configuration

File: ~/.config/claude/gitea.env

Required Variables:

GITEA_API_URL - Gitea API endpoint (e.g., https://gitea.example.com/api/v1)
GITEA_API_TOKEN - Personal access token with repo permissions

Project-Level Configuration

File: <project-root>/.env

Optional Variables:

GITEA_REPO - Repository in owner/repo format (enables project mode)

Automatic Repository Detection

If GITEA_REPO is not set, the server auto-detects the repository from your git remote:

Supported URL Formats:

SSH: ssh://git@gitea.example.com:22/owner/repo.git
SSH short: git@gitea.example.com:owner/repo.git
HTTPS: https://gitea.example.com/owner/repo.git
HTTP: http://gitea.example.com/owner/repo.git

The repository is extracted as owner/repo format automatically.

Project Directory Detection

The server finds your project directory using these strategies (in order):

CLAUDE_PROJECT_DIR environment variable (highest priority)
PWD environment variable (if .git or .env present)
Current working directory (if .git or .env present)
Falls back to company/PMO mode if no project found

Generating Gitea API Token

Log into Gitea: https://gitea.example.com
Navigate to: Settings → Applications → Manage Access Tokens
Click Generate New Token
Configure token:
- Token Name: claude-code-mcp
- Permissions:
  - ✅ repo (all) - Read/write repositories, issues, labels
  - ✅ read:org - Read organization information and labels
  - ✅ read:user - Read user information
Click Generate Token
Copy token immediately (shown only once)
Add to ~/.config/claude/gitea.env

Usage

Running the MCP Server

cd mcp-servers/gitea
source .venv/bin/activate
python -m mcp_server.server

The server communicates via JSON-RPC 2.0 over stdio.

Integration with Claude Code Plugins

The MCP server is designed to be used by Claude Code plugins via .mcp.json configuration:

{
  "mcpServers": {
    "gitea": {
      "command": "python",
      "args": ["-m", "mcp_server.server"],
      "cwd": "${CLAUDE_PLUGIN_ROOT}/../mcp-servers/gitea",
      "env": {
        "PYTHONPATH": "${CLAUDE_PLUGIN_ROOT}/../mcp-servers/gitea"
      }
    }
  }
}

Example Tool Calls

List Issues:

from mcp_server.tools.issues import IssueTools
from mcp_server.gitea_client import GiteaClient

client = GiteaClient()
issue_tools = IssueTools(client)

issues = await issue_tools.list_issues(state='open', labels=['Type/Bug'])

Suggest Labels:

from mcp_server.tools.labels import LabelTools

label_tools = LabelTools(client)

context = "Fix critical authentication bug in production API"
suggestions = await label_tools.suggest_labels(context)
# Returns: ['Type/Bug', 'Priority/Critical', 'Component/Auth', 'Component/API', ...]

Testing

Unit Tests

Run all 64 unit tests with mocks:

pytest tests/ -v

Expected: 64 passed

Integration Tests

Test with real Gitea instance:

python -c "
from mcp_server.gitea_client import GiteaClient

client = GiteaClient()
issues = client.list_issues(state='open')
print(f'Found {len(issues)} open issues')
"

Full Testing Guide

See TESTING.md for comprehensive testing instructions.

Label Taxonomy System

The system supports a dynamic 44-label taxonomy (28 org + 16 repo):

Organization Labels (28):

Agent/* (2) - Agent/Human, Agent/Claude
Complexity/* (3) - Simple, Medium, Complex
Efforts/* (5) - XS, S, M, L, XL
Priority/* (4) - Low, Medium, High, Critical
Risk/* (3) - Low, Medium, High
Source/* (4) - Development, Staging, Production, Customer
Type/* (6) - Bug, Feature, Refactor, Documentation, Test, Chore

Repository Labels (16):

Component/* (9) - Backend, Frontend, API, Database, Auth, Deploy, Testing, Docs, Infra
Tech/* (7) - Python, JavaScript, Docker, PostgreSQL, Redis, Vue, FastAPI

Labels are fetched dynamically from Gitea and suggestions adapt to the current taxonomy.

Security

Token Storage

Store tokens in ~/.config/claude/gitea.env
Set file permissions to 600 (read/write owner only)
Never commit tokens to Git
Use separate tokens for development and production

Branch Detection

The MCP server implements defense-in-depth branch detection:

MCP Tools: Check branch before operations
Agent Prompts: Warn users about branch restrictions
CLAUDE.md: Provides additional context

Input Validation

All user input is validated before API calls
Issue titles and descriptions are sanitized
Label names are checked against taxonomy
Repository names are validated

Troubleshooting

Common Issues

Module not found:

cd mcp-servers/gitea
source .venv/bin/activate

Configuration not found:

ls -la ~/.config/claude/gitea.env
# If missing, create it following installation steps

Authentication failed:

# Test token manually
curl -H "Authorization: token YOUR_TOKEN" \
  https://gitea.example.com/api/v1/user

Permission denied on branch:

# Check current branch
git branch --show-current

# Switch to development branch
git checkout development

See TESTING.md for more details.

Development

Project Structure

config.py - Hybrid configuration loader with auto-detection
gitea_client.py - Synchronous Gitea API client using requests
tools/issues.py - Issue management with branch detection
tools/labels.py - Label management and intelligent suggestions
tools/wiki.py - Wiki pages and lessons learned
tools/milestones.py - Milestone CRUD operations
tools/dependencies.py - Issue dependency tracking
tools/pull_requests.py - PR review and management
server.py - MCP server with 36 tools over JSON-RPC 2.0 stdio

Adding New Tools

Add method to GiteaClient (sync)
Add async wrapper to appropriate tool class
Register tool in server.py setup_tools()
Add unit tests
Update documentation

Testing Philosophy

Unit tests: Use mocks for fast feedback
Integration tests: Use real Gitea API for validation
Branch detection: Test all branch types
Mode detection: Test both project and company modes

Performance

Caching

Labels are cached to reduce API calls:

from functools import lru_cache

@lru_cache(maxsize=128)
def get_labels_cached(self, repo: str):
    return self.get_labels(repo)

Retry Logic

API calls include automatic retry with exponential backoff:

@retry_on_failure(max_retries=3, delay=1)
def list_issues(self, state='open', labels=None, repo=None):
    # Implementation

Changelog

See CHANGELOG.md for full version history.

Recent Updates

v1.3.0 - Pull request tools (7 tools), label creation tools (3)
v1.2.0 - Milestone management (5 tools), issue dependencies (4 tools)
v1.1.0 - Wiki & lessons learned system (7 tools)
v1.0.0 - Initial release with core issue/label tools (8 tools)

License

MIT License - Part of the Leo Claude Marketplace project.

Projman Documentation: plugins/projman/README.md
Configuration Guide: plugins/projman/CONFIGURATION.md
Testing Guide: TESTING.md

Support

For issues or questions:

Check TESTING.md troubleshooting section
Review plugins/projman/README.md for plugin documentation
Create an issue in the project repository

Built for: Leo Claude Marketplace - Project Management Plugins Tools: 36 Status: ✅ Production Ready Last Updated: 2026-02-03

README.md

Gitea MCP Server

Overview