gitea-mcp 0.1.1.dev0__py3-none-any.whl

gitea_mcp/__init__.py

@@ -0,0 +1,9 @@
+"""gitea-mcp — Model Context Protocol server for Gitea (and Forgejo, Codeberg)."""
+
+try:
+    from gitea_mcp._version import __version__
+except ImportError:
+    # Package not installed in editable mode or version file not yet generated
+    __version__ = "0.0.0.dev0"
+
+__all__ = ["__version__"]

gitea_mcp/_version.py

@@ -0,0 +1 @@
+__version__ = '0.1.1.dev0'

gitea_mcp/client.py

@@ -0,0 +1,92 @@
+"""Async HTTP client wrapper for the Gitea REST API."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+
+class GiteaError(Exception):
+    """Base exception for Gitea client errors."""
+
+
+class GiteaAPIError(GiteaError):
+    """Raised when the Gitea API returns a non-success response."""
+
+    def __init__(self, status_code: int, message: str, method: str, url: str) -> None:
+        self.status_code = status_code
+        self.method = method
+        self.url = url
+        super().__init__(f"[{method} {url}] {status_code}: {message}")
+
+
+class GiteaClient:
+    """Async HTTP client for the Gitea REST API.
+
+    Uses Personal Access Token authentication via the
+    ``Authorization: token <PAT>`` header (Gitea's convention; NOT Bearer).
+    One shared :class:`httpx.AsyncClient` per server lifetime.
+
+    All paths passed to the verb methods are appended under ``/api/v1``; pass
+    ``/repos/{owner}/{repo}`` rather than the full URL.
+    """
+
+    def __init__(self, base_url: str, token: str, timeout: float = 30.0) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._client = httpx.AsyncClient(
+            base_url=self._base_url,
+            headers={
+                "Authorization": f"token {token}",
+                "Accept": "application/json",
+            },
+            timeout=timeout,
+        )
+
+    async def close(self) -> None:
+        """Close the underlying HTTP client. Safe to call multiple times."""
+        await self._client.aclose()
+
+    async def get(
+        self, path: str, params: dict[str, Any] | None = None
+    ) -> Any:
+        response = await self._client.get(self._api_path(path), params=params)
+        return self._handle(response, method="GET", path=path)
+
+    async def post(self, path: str, json: Any | None = None) -> Any:
+        response = await self._client.post(self._api_path(path), json=json)
+        return self._handle(response, method="POST", path=path)
+
+    async def put(self, path: str, json: Any | None = None) -> Any:
+        response = await self._client.put(self._api_path(path), json=json)
+        return self._handle(response, method="PUT", path=path)
+
+    async def patch(self, path: str, json: Any | None = None) -> Any:
+        response = await self._client.patch(self._api_path(path), json=json)
+        return self._handle(response, method="PATCH", path=path)
+
+    async def delete(self, path: str) -> Any:
+        response = await self._client.delete(self._api_path(path))
+        return self._handle(response, method="DELETE", path=path)
+
+    @staticmethod
+    def _api_path(path: str) -> str:
+        """Prefix a relative path with /api/v1, leaving absolute API paths intact."""
+        if path.startswith("/api/v1"):
+            return path
+        if path.startswith("/"):
+            return f"/api/v1{path}"
+        return f"/api/v1/{path}"
+
+    def _handle(self, response: httpx.Response, method: str, path: str) -> Any:
+        if response.is_success:
+            if response.status_code == 204 or not response.content:
+                return None
+            return response.json()
+        message = response.text.strip() or response.reason_phrase
+        raise GiteaAPIError(
+            status_code=response.status_code,
+            message=message,
+            method=method,
+            url=str(response.request.url),
+        )

gitea_mcp/config.py

@@ -0,0 +1,54 @@
+"""Configuration loaded from environment variables."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Config:
+    """Runtime configuration for gitea-mcp.
+
+    Loaded once at startup from environment variables. Immutable thereafter.
+    """
+
+    base_url: str
+    token: str
+    timeout: float = 30.0
+
+    @classmethod
+    def from_env(cls) -> Config:
+        """Load configuration from environment variables.
+
+        Required:
+            GITEA_URL: Base URL of the Gitea instance (e.g. https://gitea.example.com)
+            GITEA_TOKEN: Personal Access Token
+
+        Optional:
+            GITEA_TIMEOUT: HTTP request timeout in seconds (default: 30)
+
+        Raises:
+            RuntimeError: if required variables are missing.
+        """
+        base_url = os.environ.get("GITEA_URL", "").strip()
+        if not base_url:
+            raise RuntimeError(
+                "GITEA_URL environment variable is required. "
+                "Set it to the base URL of your Gitea instance."
+            )
+
+        token = os.environ.get("GITEA_TOKEN", "").strip()
+        if not token:
+            raise RuntimeError(
+                "GITEA_TOKEN environment variable is required. "
+                "Generate a Personal Access Token in Gitea: Settings -> Applications."
+            )
+
+        timeout = float(os.environ.get("GITEA_TIMEOUT", "30"))
+
+        return cls(
+            base_url=base_url.rstrip("/"),
+            token=token,
+            timeout=timeout,
+        )

gitea_mcp/server.py

@@ -0,0 +1,64 @@
+"""MCP server entry point. Registers tools and runs stdio transport."""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+
+from fastmcp import FastMCP
+
+from gitea_mcp.client import GiteaClient
+from gitea_mcp.config import Config
+
+# Module-level FastMCP instance so tool modules can register against it.
+mcp: FastMCP = FastMCP("gitea-mcp")
+
+# Singleton client populated at startup. Tool modules access via get_client().
+_client: GiteaClient | None = None
+
+
+def get_client() -> GiteaClient:
+    """Return the singleton :class:`GiteaClient`.
+
+    Must be called after :func:`main` has initialized the client.
+    """
+    if _client is None:
+        raise RuntimeError(
+            "GiteaClient not initialized. The gitea-mcp server must be started "
+            "via the gitea-mcp entry point so the client is available before "
+            "any tools are called."
+        )
+    return _client
+
+
+# Import tool modules so their @mcp.tool() registrations execute on module load.
+# Ordering doesn't matter; each module registers its own tools against `mcp`.
+from gitea_mcp.tools import issues, releases, repos  # noqa: E402, F401
+
+
+def main() -> None:
+    """Console-script entry point.
+
+    1. Loads configuration from environment variables.
+    2. Initializes the singleton GiteaClient.
+    3. Runs the MCP server over stdio (blocks until the client disconnects).
+    4. Closes the GiteaClient on shutdown.
+    """
+    global _client
+
+    config = Config.from_env()
+    _client = GiteaClient(
+        base_url=config.base_url,
+        token=config.token,
+        timeout=config.timeout,
+    )
+    try:
+        mcp.run()
+    finally:
+        # Best-effort cleanup. If the event loop is already closed, ignore.
+        with contextlib.suppress(RuntimeError):
+            asyncio.run(_client.close())
+
+
+if __name__ == "__main__":
+    main()

gitea_mcp/tools/__init__.py

@@ -0,0 +1,5 @@
+"""MCP tool definitions, organized by Gitea resource family.
+
+Each submodule registers its tools against the FastMCP instance defined in
+``gitea_mcp.server``.
+"""

gitea_mcp/tools/issues.py

@@ -0,0 +1,239 @@
+"""MCP tools for Gitea issues."""
+
+from __future__ import annotations
+
+from typing import Annotated, Any
+
+from pydantic import Field
+
+from gitea_mcp.client import GiteaClient, GiteaError
+from gitea_mcp.server import get_client, mcp
+
+# ---- Internal helpers ------------------------------------------------------
+
+
+async def _list_all_labels(
+    client: GiteaClient, owner: str, repo: str
+) -> list[dict[str, Any]]:
+    """Page through every label defined in a repository."""
+    all_labels: list[dict[str, Any]] = []
+    page = 1
+    while True:
+        batch = await client.get(
+            f"/repos/{owner}/{repo}/labels",
+            params={"page": page, "limit": 50},
+        )
+        if not batch:
+            break
+        all_labels.extend(batch)
+        if len(batch) < 50:
+            break
+        page += 1
+    return all_labels
+
+
+async def _resolve_label_ids(
+    client: GiteaClient, owner: str, repo: str, label_names: list[str]
+) -> list[int]:
+    """Resolve a list of label names to the integer IDs Gitea's issue API expects.
+
+    Gitea's create-issue and replace-issue-labels endpoints take ``labels`` as a
+    list of integer IDs, not names. This helper fetches the repo's labels once
+    and maps the names in. Raises :class:`GiteaError` if any name doesn't match
+    a defined label, including the available label names in the error message
+    so the caller knows what's valid.
+    """
+    if not label_names:
+        return []
+    all_labels = await _list_all_labels(client, owner, repo)
+    name_to_id = {label["name"]: label["id"] for label in all_labels}
+    missing = [name for name in label_names if name not in name_to_id]
+    if missing:
+        raise GiteaError(
+            f"Labels not found in {owner}/{repo}: {missing}. "
+            f"Available labels: {sorted(name_to_id.keys())}"
+        )
+    return [name_to_id[name] for name in label_names]
+
+
+# ---- Tools -----------------------------------------------------------------
+
+
+@mcp.tool()
+async def create_issue(
+    owner: Annotated[str, Field(description="Repository owner (user or organization name)")],
+    repo: Annotated[str, Field(description="Repository name")],
+    title: Annotated[str, Field(description="Issue title")],
+    body: Annotated[str, Field(description="Issue body in Markdown")] = "",
+    labels: Annotated[
+        list[str] | None,
+        Field(description="Label names to apply to the new issue (resolved to IDs automatically)"),
+    ] = None,
+    assignees: Annotated[
+        list[str] | None,
+        Field(description="Usernames to assign to the new issue"),
+    ] = None,
+    milestone: Annotated[int | None, Field(description="Milestone ID to attach")] = None,
+) -> dict[str, Any]:
+    """Create a new issue in a Gitea repository.
+
+    Returns the full Gitea Issue object including the assigned number, URL, and
+    metadata. Label names are resolved to IDs against the repository's label
+    set; an unknown label name fails the call cleanly with the list of valid
+    names.
+    """
+    client = get_client()
+    payload: dict[str, Any] = {"title": title, "body": body}
+    if assignees:
+        payload["assignees"] = assignees
+    if milestone is not None:
+        payload["milestone"] = milestone
+    if labels:
+        payload["labels"] = await _resolve_label_ids(client, owner, repo, labels)
+    issue: dict[str, Any] = await client.post(
+        f"/repos/{owner}/{repo}/issues", json=payload
+    )
+    return issue
+
+
+@mcp.tool()
+async def list_issues(
+    owner: Annotated[str, Field(description="Repository owner (user or organization name)")],
+    repo: Annotated[str, Field(description="Repository name")],
+    state: Annotated[
+        str, Field(description="Filter by state: 'open', 'closed', or 'all'")
+    ] = "open",
+    labels: Annotated[
+        str | None,
+        Field(description="Comma-separated label names to filter by"),
+    ] = None,
+    assignee: Annotated[
+        str | None,
+        Field(description="Filter to issues assigned to this username"),
+    ] = None,
+    page: Annotated[int, Field(description="Page number (1-indexed)")] = 1,
+    limit: Annotated[int, Field(description="Items per page (max 50)")] = 30,
+) -> list[dict[str, Any]]:
+    """List issues in a Gitea repository.
+
+    Pull requests are excluded; only true issues are returned. Filters compose
+    (state AND labels AND assignee).
+    """
+    client = get_client()
+    params: dict[str, Any] = {
+        "state": state,
+        "type": "issues",  # exclude pull requests
+        "page": page,
+        "limit": limit,
+    }
+    if labels:
+        params["labels"] = labels
+    if assignee:
+        params["assigned_by"] = assignee
+    issues: list[dict[str, Any]] = await client.get(
+        f"/repos/{owner}/{repo}/issues", params=params
+    )
+    return issues
+
+
+@mcp.tool()
+async def get_issue(
+    owner: Annotated[str, Field(description="Repository owner")],
+    repo: Annotated[str, Field(description="Repository name")],
+    issue_number: Annotated[int, Field(description="Issue number (the #N in the URL)")],
+) -> dict[str, Any]:
+    """Get a single issue by number, including all of its comments.
+
+    The returned object is the standard Gitea Issue payload, with an additional
+    ``comments_list`` field containing the full list of Comment objects. The
+    existing top-level ``comments`` integer field (comment count) is preserved.
+    """
+    client = get_client()
+    issue: dict[str, Any] = await client.get(
+        f"/repos/{owner}/{repo}/issues/{issue_number}"
+    )
+    issue["comments_list"] = await client.get(
+        f"/repos/{owner}/{repo}/issues/{issue_number}/comments"
+    )
+    return issue
+
+
+@mcp.tool()
+async def update_issue(
+    owner: Annotated[str, Field(description="Repository owner")],
+    repo: Annotated[str, Field(description="Repository name")],
+    issue_number: Annotated[int, Field(description="Issue number")],
+    title: Annotated[str | None, Field(description="New title")] = None,
+    body: Annotated[str | None, Field(description="New body (Markdown)")] = None,
+    state: Annotated[
+        str | None,
+        Field(description="New state: 'open' or 'closed'"),
+    ] = None,
+    labels: Annotated[
+        list[str] | None,
+        Field(description="Replace labels with this exact set (names; pass [] to clear)"),
+    ] = None,
+    assignees: Annotated[
+        list[str] | None,
+        Field(description="Replace assignees with this exact set of usernames"),
+    ] = None,
+    milestone: Annotated[
+        int | None,
+        Field(description="Milestone ID to attach; pass 0 to clear the milestone"),
+    ] = None,
+) -> dict[str, Any]:
+    """Update an existing issue's title, body, state, assignees, milestone, or labels.
+
+    Each argument is independent — pass only the fields you want to change.
+    Labels are replaced atomically against the new set (passing ``[]`` removes
+    all labels). Other list fields (assignees) follow the same replace semantics.
+    """
+    client = get_client()
+    payload: dict[str, Any] = {}
+    if title is not None:
+        payload["title"] = title
+    if body is not None:
+        payload["body"] = body
+    if state is not None:
+        payload["state"] = state
+    if assignees is not None:
+        payload["assignees"] = assignees
+    if milestone is not None:
+        # Gitea convention: milestone=0 in the request clears the milestone.
+        # We send null in that case, which Gitea also accepts and is unambiguous.
+        payload["milestone"] = milestone if milestone > 0 else None
+
+    issue: dict[str, Any]
+    if payload:
+        issue = await client.patch(
+            f"/repos/{owner}/{repo}/issues/{issue_number}", json=payload
+        )
+    else:
+        # No PATCH-level changes — fetch the current issue so the caller still
+        # gets the up-to-date object after the labels update below.
+        issue = await client.get(f"/repos/{owner}/{repo}/issues/{issue_number}")
+
+    if labels is not None:
+        label_ids = await _resolve_label_ids(client, owner, repo, labels)
+        issue["labels"] = await client.put(
+            f"/repos/{owner}/{repo}/issues/{issue_number}/labels",
+            json={"labels": label_ids},
+        )
+
+    return issue
+
+
+@mcp.tool()
+async def add_comment(
+    owner: Annotated[str, Field(description="Repository owner")],
+    repo: Annotated[str, Field(description="Repository name")],
+    issue_number: Annotated[int, Field(description="Issue number")],
+    body: Annotated[str, Field(description="Comment body (Markdown)")],
+) -> dict[str, Any]:
+    """Add a comment to an existing issue. Returns the created Comment object."""
+    client = get_client()
+    comment: dict[str, Any] = await client.post(
+        f"/repos/{owner}/{repo}/issues/{issue_number}/comments",
+        json={"body": body},
+    )
+    return comment

gitea_mcp/tools/releases.py

@@ -0,0 +1,88 @@
+"""MCP tools for Gitea releases."""
+
+from __future__ import annotations
+
+from typing import Annotated, Any
+
+from pydantic import Field
+
+from gitea_mcp.server import get_client, mcp
+
+
+@mcp.tool()
+async def list_releases(
+    owner: Annotated[str, Field(description="Repository owner")],
+    repo: Annotated[str, Field(description="Repository name")],
+    page: Annotated[int, Field(description="Page number (1-indexed)")] = 1,
+    limit: Annotated[int, Field(description="Items per page (max 50)")] = 30,
+) -> list[dict[str, Any]]:
+    """List releases for a repository.
+
+    Returns the standard Gitea Release object array, including drafts and
+    pre-releases. Sort order is newest first.
+    """
+    client = get_client()
+    releases: list[dict[str, Any]] = await client.get(
+        f"/repos/{owner}/{repo}/releases",
+        params={"page": page, "limit": limit},
+    )
+    return releases
+
+
+@mcp.tool()
+async def create_release(
+    owner: Annotated[str, Field(description="Repository owner")],
+    repo: Annotated[str, Field(description="Repository name")],
+    tag_name: Annotated[
+        str,
+        Field(
+            description=(
+                "Tag this release is based on. If the tag does not already exist "
+                "in the repository, Gitea creates it at the time of release."
+            ),
+        ),
+    ],
+    name: Annotated[str, Field(description="Release title")],
+    body: Annotated[str, Field(description="Release notes in Markdown")] = "",
+    target_commitish: Annotated[
+        str | None,
+        Field(
+            description=(
+                "Branch name or commit SHA the tag should point at. "
+                "Defaults to the repository's default branch. "
+                "Ignored if the tag already exists."
+            ),
+        ),
+    ] = None,
+    draft: Annotated[
+        bool,
+        Field(description="Save as draft without publishing"),
+    ] = False,
+    prerelease: Annotated[
+        bool,
+        Field(description="Mark as a pre-release"),
+    ] = False,
+) -> dict[str, Any]:
+    """Create a new release in a repository.
+
+    .. warning::
+
+       Side effects: if ``tag_name`` does not already exist in the repository,
+       Gitea creates the tag at the current ``target_commitish`` (or default
+       branch). Creating a draft does NOT skip tag creation — both drafts and
+       published releases will leave a tag in the repo.
+    """
+    client = get_client()
+    payload: dict[str, Any] = {
+        "tag_name": tag_name,
+        "name": name,
+        "body": body,
+        "draft": draft,
+        "prerelease": prerelease,
+    }
+    if target_commitish is not None:
+        payload["target_commitish"] = target_commitish
+    release: dict[str, Any] = await client.post(
+        f"/repos/{owner}/{repo}/releases", json=payload
+    )
+    return release

gitea_mcp/tools/repos.py

@@ -0,0 +1,95 @@
+"""MCP tools for Gitea repository metadata."""
+
+from __future__ import annotations
+
+from typing import Annotated, Any
+
+from pydantic import Field
+
+from gitea_mcp.client import GiteaAPIError
+from gitea_mcp.server import get_client, mcp
+
+
+@mcp.tool()
+async def list_repos(
+    owner: Annotated[
+        str | None,
+        Field(
+            description=(
+                "Username or organization to list repos for. "
+                "Leave empty to list repositories accessible to the authenticated user."
+            ),
+        ),
+    ] = None,
+    page: Annotated[int, Field(description="Page number (1-indexed)")] = 1,
+    limit: Annotated[int, Field(description="Items per page (max 50)")] = 30,
+) -> list[dict[str, Any]]:
+    """List repositories.
+
+    Three modes:
+
+    - ``owner`` empty: returns repositories accessible to the authenticated user
+      (``GET /user/repos``).
+    - ``owner`` is a user: returns that user's repositories
+      (``GET /users/{owner}/repos``).
+    - ``owner`` is an organization: returns that org's repositories
+      (``GET /orgs/{owner}/repos`` — automatically tried as a fallback when the
+      user endpoint 404s, so callers don't need to know which it is).
+    """
+    client = get_client()
+    params: dict[str, Any] = {"page": page, "limit": limit}
+
+    result: list[dict[str, Any]]
+    if not owner:
+        result = await client.get("/user/repos", params=params)
+        return result
+
+    try:
+        result = await client.get(f"/users/{owner}/repos", params=params)
+        return result
+    except GiteaAPIError as e:
+        if e.status_code == 404:
+            # Owner is likely an organization — fall back transparently.
+            result = await client.get(f"/orgs/{owner}/repos", params=params)
+            return result
+        raise
+
+
+@mcp.tool()
+async def list_labels(
+    owner: Annotated[str, Field(description="Repository owner")],
+    repo: Annotated[str, Field(description="Repository name")],
+    page: Annotated[int, Field(description="Page number (1-indexed)")] = 1,
+    limit: Annotated[int, Field(description="Items per page (max 50)")] = 30,
+) -> list[dict[str, Any]]:
+    """List labels defined in a repository.
+
+    Returns the standard Gitea Label object: ``{id, name, color, description, ...}``.
+    Use the ``id`` values when calling tools that take ``label_ids`` directly;
+    most tools accept label *names* and resolve to IDs internally.
+    """
+    client = get_client()
+    labels: list[dict[str, Any]] = await client.get(
+        f"/repos/{owner}/{repo}/labels",
+        params={"page": page, "limit": limit},
+    )
+    return labels
+
+
+@mcp.tool()
+async def list_milestones(
+    owner: Annotated[str, Field(description="Repository owner")],
+    repo: Annotated[str, Field(description="Repository name")],
+    state: Annotated[
+        str, Field(description="Filter by state: 'open', 'closed', or 'all'")
+    ] = "open",
+    page: Annotated[int, Field(description="Page number (1-indexed)")] = 1,
+    limit: Annotated[int, Field(description="Items per page (max 50)")] = 30,
+) -> list[dict[str, Any]]:
+    """List milestones in a repository, optionally filtered by state."""
+    client = get_client()
+    milestones: list[dict[str, Any]] = await client.get(
+        f"/repos/{owner}/{repo}/milestones",
+        params={"state": state, "page": page, "limit": limit},
+    )
+    return milestones

gitea_mcp-0.1.1.dev0.dist-info/METADATA

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: gitea-mcp
+Version: 0.1.1.dev0
+Summary: Model Context Protocol server for Gitea (and Forgejo, Codeberg).
+Author-email: Sam Ware <samuel@waretech.services>
+License: MIT
+Project-URL: Homepage, https://github.com/werebear73/gitea-mcp
+Project-URL: Issues, https://github.com/werebear73/gitea-mcp/issues
+Project-URL: Source, https://github.com/werebear73/gitea-mcp
+Keywords: mcp,gitea,forgejo,codeberg,model-context-protocol,llm,ai
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastmcp>=2.0.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: pytest-httpx>=0.30; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Dynamic: license-file
+
+# gitea-mcp
+
+A [Model Context Protocol](https://modelcontextprotocol.io) server for [Gitea](https://gitea.io) — lets AI assistants (Claude, ChatGPT, Copilot, and anything else that speaks MCP) read, create, and manage issues, repositories, and releases on any Gitea instance you can reach.
+
+Also works against **[Forgejo](https://forgejo.org)** and **[Codeberg](https://codeberg.org)** (API-compatible).
+
+## Why
+
+Self-hosted Gitea is a popular GitHub alternative for solo developers, small teams, and privacy-conscious organizations. With this MCP server installed, your AI assistant can:
+
+- File audit findings or refactor notes as Gitea issues without you leaving the chat
+- Triage a repo's open issues in natural language
+- Cut a release at the end of a coding session
+- Comment on issues across multiple repos in one pass
+
+## Features
+
+| Resource | Tools |
+| --- | --- |
+| Issues | `create_issue`, `list_issues`, `get_issue`, `update_issue`, `add_comment` |
+| Repos | `list_repos`, `list_labels`, `list_milestones` |
+| Releases | `list_releases`, `create_release` |
+
+- Bearer authentication via Personal Access Token (PAT)
+- Async HTTP via `httpx` and `FastMCP`
+- Works with self-hosted Gitea, Forgejo, and Codeberg
+
+## Quick Start
+
+### 1. Install
+
+```bash
+pip install gitea-mcp
+```
+
+Or with [`uv`](https://docs.astral.sh/uv/):
+
+```bash
+uv pip install gitea-mcp
+```
+
+### 2. Generate a Personal Access Token
+
+In your Gitea instance, go to **Settings → Applications → Generate New Token** and grant at least:
+
+- `read:repository`
+- `write:issue`
+- `read:user`
+
+Add `write:repository` if you also want to create releases.
+
+### 3. Configure your MCP client
+
+Add `gitea-mcp` to your MCP client configuration:
+
+```json
+{
+  "mcpServers": {
+    "gitea": {
+      "command": "gitea-mcp",
+      "env": {
+        "GITEA_URL": "https://your-gitea-instance.example.com",
+        "GITEA_TOKEN": "your-personal-access-token"
+      }
+    }
+  }
+}
+```
+
+See [`mcp.json`](mcp.json) for a complete example. The same shape works for Claude Desktop, VS Code, Cowork, Claude Code, and any other MCP-compatible client.
+
+## Configuration
+
+Configuration is read from environment variables.
+
+| Variable | Required | Default | Description |
+| --- | --- | --- | --- |
+| `GITEA_URL` | Yes | — | Base URL of your Gitea instance (e.g., `https://gitea.example.com`) |
+| `GITEA_TOKEN` | Yes | — | Personal Access Token from your Gitea user settings |
+| `GITEA_TIMEOUT` | No | `30` | HTTP request timeout in seconds |
+
+## Compatibility
+
+| Server | Status |
+| --- | --- |
+| Gitea (self-hosted) | ✅ Primary target |
+| Forgejo | ✅ Expected to work (API-compatible) |
+| Codeberg | ✅ Expected to work (Codeberg runs Forgejo) |
+
+## Development
+
+```bash
+git clone https://github.com/werebear73/gitea-mcp.git
+cd gitea-mcp
+pip install -e ".[dev]"
+pytest
+```
+
+## Versioning
+
+Semantic versioning, derived from git tags via `setuptools_scm`. See [`VERSIONING.md`](VERSIONING.md) for the release process.
+
+## Contributing
+
+Issues and pull requests welcome. For substantial changes, please open an issue first to discuss the approach.
+
+## License
+
+[MIT](LICENSE) — use it however you like, including commercial products.
+
+---
+
+Built by [Waretech Services](https://waretech.services).

gitea_mcp-0.1.1.dev0.dist-info/RECORD

@@ -0,0 +1,15 @@
+gitea_mcp/__init__.py,sha256=bZFvKlD5VDuhyzuInqhYGOEhcfK2BT4I3q-OcuSHnCk,295
+gitea_mcp/_version.py,sha256=oPswspFxAXNlLuTZyMi9XRnaPJZToIRg6GOAdbA5WuM,27
+gitea_mcp/client.py,sha256=qaLWrGmTCa2331gAuVzmY_cm3sBfkXIzr_Mrx9iAp7U,3350
+gitea_mcp/config.py,sha256=ozY7Gp-K0jVLHto6OyA2F2A53t-H90e-S1U4Y3aNUUY,1539
+gitea_mcp/server.py,sha256=2V_CgDK-Z3lPO_XcsUOxWbrjpTLdp4jJBH_QS18IXjM,1854
+gitea_mcp/tools/__init__.py,sha256=2G_XMRLzAB4wLjVBawMuVxSYhlu2wWi8AkzbLTHJxXM,163
+gitea_mcp/tools/issues.py,sha256=azN3aHXHIeAw9QhCLaSEOkgV9LjDOn6NpcAz74qv3xc,8802
+gitea_mcp/tools/releases.py,sha256=zvWzm2JjTbUIQW8SZSSBjhMiqcEo-At3TMlJnAPX1DI,2826
+gitea_mcp/tools/repos.py,sha256=d_NeJG-l7Y8PqVeuLYiUHNfOP68dPJ_rGJAs__CCbco,3378
+gitea_mcp-0.1.1.dev0.dist-info/licenses/LICENSE,sha256=-haC-gxLVoaxywPnh135rjt4qb55WDqOp7n3-I6STns,1065
+gitea_mcp-0.1.1.dev0.dist-info/METADATA,sha256=184_kNsj-AgZIQJpymdSQbeedsVcO3mohyoniyYFd1Y,4684
+gitea_mcp-0.1.1.dev0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+gitea_mcp-0.1.1.dev0.dist-info/entry_points.txt,sha256=PjRHlfQDMINFlBt4maFz_PWZ0p8t38Rw3br6-w-hZis,52
+gitea_mcp-0.1.1.dev0.dist-info/top_level.txt,sha256=anwGYTKslQDgerLVaH7Ded7ivajJbXfUAjcnmZeslWk,10
+gitea_mcp-0.1.1.dev0.dist-info/RECORD,,

gitea_mcp-0.1.1.dev0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

gitea_mcp-0.1.1.dev0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+gitea-mcp = gitea_mcp.server:main

gitea_mcp-0.1.1.dev0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sam Ware
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gitea_mcp-0.1.1.dev0.dist-info/top_level.txt

@@ -0,0 +1 @@
+gitea_mcp