github-mcp-connector 0.1.0__py3-none-any.whl

github_mcp/__init__.py

@@ -0,0 +1,10 @@
+"""A Model Context Protocol (MCP) connector for GitHub.
+
+Exposes a focused set of GitHub REST API operations as MCP tools so that
+Claude (Desktop, Code, or any MCP client) can read repositories, issues,
+pull requests, commits, and code, and optionally open issues and comments.
+"""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

github_mcp/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running the connector with ``python -m github_mcp``."""
+
+from .server import main
+
+if __name__ == "__main__":
+    main()

github_mcp/client.py

@@ -0,0 +1,140 @@
+"""A thin async wrapper around the GitHub REST API.
+
+The wrapper is intentionally small: it handles authentication, the standard
+headers GitHub expects, error translation, and a tiny bit of pagination. Each
+MCP tool in :mod:`github_mcp.server` builds on top of these primitives.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from .config import Config
+
+GITHUB_ACCEPT = "application/vnd.github+json"
+GITHUB_API_VERSION = "2022-11-28"
+
+
+class GitHubError(RuntimeError):
+    """Raised when the GitHub API returns an error response.
+
+    The message is formatted to be useful when surfaced back to an LLM: it
+    includes the HTTP status, the requested method/path, and GitHub's own
+    error message when one is available.
+    """
+
+    def __init__(self, status_code: int, method: str, url: str, detail: str) -> None:
+        self.status_code = status_code
+        self.method = method
+        self.url = url
+        self.detail = detail
+        super().__init__(f"GitHub API {method} {url} failed ({status_code}): {detail}")
+
+
+class GitHubClient:
+    """Minimal async GitHub REST client.
+
+    Use as an async context manager so the underlying connection pool is
+    closed cleanly::
+
+        async with GitHubClient(config) as gh:
+            user = await gh.get("/user")
+    """
+
+    def __init__(
+        self, config: Config, *, transport: httpx.BaseTransport | None = None
+    ) -> None:
+        self._config = config
+        headers = {
+            "Accept": GITHUB_ACCEPT,
+            "X-GitHub-Api-Version": GITHUB_API_VERSION,
+            "User-Agent": config.user_agent,
+        }
+        if config.token:
+            headers["Authorization"] = f"Bearer {config.token}"
+        # `transport` is an injection seam used by tests to mock the API; in
+        # normal operation it is None and httpx uses its default transport.
+        self._client = httpx.AsyncClient(
+            base_url=config.api_url,
+            headers=headers,
+            timeout=config.timeout,
+            follow_redirects=True,
+            transport=transport,
+        )
+
+    async def __aenter__(self) -> "GitHubClient":
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    # -- core request helpers -------------------------------------------------
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: dict[str, Any] | None = None,
+        accept: str | None = None,
+    ) -> httpx.Response:
+        headers = {"Accept": accept} if accept else None
+        clean_params = (
+            {k: v for k, v in params.items() if v is not None} if params else None
+        )
+        try:
+            response = await self._client.request(
+                method, path, params=clean_params, json=json, headers=headers
+            )
+        except httpx.HTTPError as exc:  # network/timeout errors
+            raise GitHubError(0, method, path, f"request error: {exc}") from exc
+
+        if response.status_code >= 400:
+            raise GitHubError(
+                response.status_code,
+                method,
+                str(response.request.url),
+                _extract_error_detail(response),
+            )
+        return response
+
+    async def get(
+        self, path: str, *, params: dict[str, Any] | None = None
+    ) -> Any:
+        response = await self._request("GET", path, params=params)
+        if not response.content:
+            return None
+        return response.json()
+
+    async def get_raw(
+        self, path: str, *, params: dict[str, Any] | None = None, accept: str
+    ) -> str:
+        response = await self._request("GET", path, params=params, accept=accept)
+        return response.text
+
+    async def post(self, path: str, *, json: dict[str, Any]) -> Any:
+        response = await self._request("POST", path, json=json)
+        if not response.content:
+            return None
+        return response.json()
+
+
+def _extract_error_detail(response: httpx.Response) -> str:
+    """Pull the most useful human-readable error message out of a response."""
+    try:
+        payload = response.json()
+    except ValueError:
+        return response.text[:500] or response.reason_phrase
+    if isinstance(payload, dict):
+        message = payload.get("message", "")
+        errors = payload.get("errors")
+        if errors:
+            return f"{message}: {errors}"
+        return message or str(payload)
+    return str(payload)

github_mcp/config.py

@@ -0,0 +1,62 @@
+"""Configuration for the GitHub MCP connector.
+
+All configuration is read from environment variables so the server can be
+launched by an MCP client (Claude Desktop/Code) with nothing but an ``env``
+block. See ``.env.example`` for the full list.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+DEFAULT_API_URL = "https://api.github.com"
+
+# Environment variable names, in priority order, that may hold the token.
+_TOKEN_ENV_VARS = (
+    "GITHUB_TOKEN",
+    "GITHUB_PERSONAL_ACCESS_TOKEN",
+    "GH_TOKEN",
+)
+
+
+def _read_token() -> str | None:
+    for name in _TOKEN_ENV_VARS:
+        value = os.environ.get(name)
+        if value:
+            return value.strip()
+    return None
+
+
+def _read_bool(name: str, default: bool = False) -> bool:
+    raw = os.environ.get(name)
+    if raw is None:
+        return default
+    return raw.strip().lower() in {"1", "true", "yes", "on"}
+
+
+@dataclass(frozen=True)
+class Config:
+    """Resolved runtime configuration."""
+
+    token: str | None
+    api_url: str
+    read_only: bool
+    timeout: float
+    user_agent: str
+
+    @classmethod
+    def from_env(cls) -> "Config":
+        api_url = os.environ.get("GITHUB_API_URL", DEFAULT_API_URL).rstrip("/")
+        timeout_raw = os.environ.get("GITHUB_MCP_TIMEOUT", "30")
+        try:
+            timeout = float(timeout_raw)
+        except ValueError:
+            timeout = 30.0
+        return cls(
+            token=_read_token(),
+            api_url=api_url,
+            read_only=_read_bool("GITHUB_MCP_READ_ONLY", default=False),
+            timeout=timeout,
+            user_agent=os.environ.get("GITHUB_MCP_USER_AGENT", "github-mcp-connector"),
+        )

github_mcp/server.py

@@ -0,0 +1,477 @@
+"""The GitHub MCP connector server.
+
+Defines the FastMCP server and the GitHub tools it exposes. Run it with::
+
+    python -m github_mcp            # stdio transport (Claude Desktop/Code)
+    python -m github_mcp --http     # streamable HTTP transport
+
+Write tools (creating issues, commenting) are disabled when the environment
+variable ``GITHUB_MCP_READ_ONLY`` is truthy.
+"""
+
+from __future__ import annotations
+
+import base64
+from typing import Any
+
+from mcp.server.fastmcp import FastMCP
+
+from .client import GitHubClient, GitHubError
+from .config import Config
+
+config = Config.from_env()
+
+INSTRUCTIONS = """\
+This server connects Claude to GitHub via the REST API.
+
+Use it to look up repositories, read files and commit history, triage issues,
+and review pull requests. Always pass `owner` and `repo` separately (for the
+repo `octocat/hello-world`, owner is `octocat` and repo is `hello-world`).
+
+For free-text discovery use the `search_*` tools, which accept GitHub search
+qualifiers (e.g. `repo:owner/name`, `is:open`, `label:bug`, `language:python`).
+"""
+
+mcp = FastMCP("github", instructions=INSTRUCTIONS)
+
+
+# ---------------------------------------------------------------------------
+# helpers
+# ---------------------------------------------------------------------------
+
+
+def _require_token() -> None:
+    if not config.token:
+        raise GitHubError(
+            401,
+            "AUTH",
+            config.api_url,
+            "No GitHub token configured. Set GITHUB_TOKEN (or "
+            "GITHUB_PERSONAL_ACCESS_TOKEN) in the connector environment.",
+        )
+
+
+def _require_write() -> None:
+    if config.read_only:
+        raise GitHubError(
+            403,
+            "WRITE",
+            config.api_url,
+            "This connector is running in read-only mode "
+            "(GITHUB_MCP_READ_ONLY is set); write operations are disabled.",
+        )
+
+
+def _summarize_repo(repo: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "full_name": repo.get("full_name"),
+        "description": repo.get("description"),
+        "private": repo.get("private"),
+        "fork": repo.get("fork"),
+        "default_branch": repo.get("default_branch"),
+        "language": repo.get("language"),
+        "stars": repo.get("stargazers_count"),
+        "forks": repo.get("forks_count"),
+        "open_issues": repo.get("open_issues_count"),
+        "html_url": repo.get("html_url"),
+        "updated_at": repo.get("updated_at"),
+    }
+
+
+def _summarize_issue(issue: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "number": issue.get("number"),
+        "title": issue.get("title"),
+        "state": issue.get("state"),
+        "user": (issue.get("user") or {}).get("login"),
+        "labels": [label.get("name") for label in issue.get("labels", [])],
+        "comments": issue.get("comments"),
+        "is_pull_request": "pull_request" in issue,
+        "created_at": issue.get("created_at"),
+        "updated_at": issue.get("updated_at"),
+        "html_url": issue.get("html_url"),
+    }
+
+
+def _summarize_pull(pull: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "number": pull.get("number"),
+        "title": pull.get("title"),
+        "state": pull.get("state"),
+        "draft": pull.get("draft"),
+        "user": (pull.get("user") or {}).get("login"),
+        "head": (pull.get("head") or {}).get("ref"),
+        "base": (pull.get("base") or {}).get("ref"),
+        "merged": pull.get("merged"),
+        "mergeable": pull.get("mergeable"),
+        "comments": pull.get("comments"),
+        "review_comments": pull.get("review_comments"),
+        "changed_files": pull.get("changed_files"),
+        "additions": pull.get("additions"),
+        "deletions": pull.get("deletions"),
+        "created_at": pull.get("created_at"),
+        "html_url": pull.get("html_url"),
+    }
+
+
+def _summarize_commit(commit: dict[str, Any]) -> dict[str, Any]:
+    detail = commit.get("commit", {})
+    author = detail.get("author", {})
+    return {
+        "sha": commit.get("sha"),
+        "message": detail.get("message"),
+        "author": author.get("name"),
+        "date": author.get("date"),
+        "html_url": commit.get("html_url"),
+    }
+
+
+# ---------------------------------------------------------------------------
+# read tools
+# ---------------------------------------------------------------------------
+
+
+@mcp.tool()
+async def get_authenticated_user() -> dict[str, Any]:
+    """Return the GitHub account the connector's token authenticates as.
+
+    Useful as a connection/health check and to confirm which identity and
+    permissions the connector is operating with.
+    """
+    _require_token()
+    async with GitHubClient(config) as gh:
+        user = await gh.get("/user")
+    return {
+        "login": user.get("login"),
+        "name": user.get("name"),
+        "type": user.get("type"),
+        "public_repos": user.get("public_repos"),
+        "html_url": user.get("html_url"),
+    }
+
+
+@mcp.tool()
+async def search_repositories(query: str, limit: int = 10) -> list[dict[str, Any]]:
+    """Search GitHub for repositories matching a query.
+
+    `query` accepts GitHub search syntax, e.g. `language:python topic:mcp` or
+    `org:anthropics stars:>100`. Returns up to `limit` (max 50) repositories.
+    """
+    _require_token()
+    limit = max(1, min(limit, 50))
+    async with GitHubClient(config) as gh:
+        result = await gh.get(
+            "/search/repositories", params={"q": query, "per_page": limit}
+        )
+    return [_summarize_repo(item) for item in result.get("items", [])]
+
+
+@mcp.tool()
+async def get_repository(owner: str, repo: str) -> dict[str, Any]:
+    """Get metadata for a single repository (description, default branch, stars, etc.)."""
+    _require_token()
+    async with GitHubClient(config) as gh:
+        data = await gh.get(f"/repos/{owner}/{repo}")
+    return _summarize_repo(data)
+
+
+@mcp.tool()
+async def list_branches(owner: str, repo: str, limit: int = 30) -> list[dict[str, Any]]:
+    """List branches in a repository, with the head commit SHA for each."""
+    _require_token()
+    limit = max(1, min(limit, 100))
+    async with GitHubClient(config) as gh:
+        branches = await gh.get(
+            f"/repos/{owner}/{repo}/branches", params={"per_page": limit}
+        )
+    return [
+        {
+            "name": branch.get("name"),
+            "sha": (branch.get("commit") or {}).get("sha"),
+            "protected": branch.get("protected"),
+        }
+        for branch in branches
+    ]
+
+
+@mcp.tool()
+async def get_file_contents(
+    owner: str, repo: str, path: str, ref: str | None = None
+) -> dict[str, Any]:
+    """Read a file or list a directory in a repository.
+
+    `path` is the path within the repo (e.g. `src/app.py`). `ref` is an
+    optional branch, tag, or commit SHA (defaults to the default branch). For a
+    file the decoded text content is returned; for a directory a listing is
+    returned instead.
+    """
+    _require_token()
+    async with GitHubClient(config) as gh:
+        data = await gh.get(
+            f"/repos/{owner}/{repo}/contents/{path}", params={"ref": ref}
+        )
+
+    if isinstance(data, list):
+        return {
+            "type": "directory",
+            "path": path,
+            "entries": [
+                {"name": e.get("name"), "path": e.get("path"), "type": e.get("type")}
+                for e in data
+            ],
+        }
+
+    encoding = data.get("encoding")
+    raw = data.get("content", "")
+    if encoding == "base64":
+        try:
+            text = base64.b64decode(raw).decode("utf-8")
+        except UnicodeDecodeError:
+            return {
+                "type": "file",
+                "path": data.get("path"),
+                "size": data.get("size"),
+                "binary": True,
+                "message": "File is binary and cannot be displayed as text.",
+                "html_url": data.get("html_url"),
+            }
+    else:
+        text = raw
+    return {
+        "type": "file",
+        "path": data.get("path"),
+        "size": data.get("size"),
+        "sha": data.get("sha"),
+        "content": text,
+        "html_url": data.get("html_url"),
+    }
+
+
+@mcp.tool()
+async def list_commits(
+    owner: str,
+    repo: str,
+    sha: str | None = None,
+    path: str | None = None,
+    limit: int = 20,
+) -> list[dict[str, Any]]:
+    """List recent commits on a repository.
+
+    Optionally narrow to a branch/SHA via `sha` or to commits touching a single
+    file via `path`. Returns up to `limit` (max 50) commits.
+    """
+    _require_token()
+    limit = max(1, min(limit, 50))
+    async with GitHubClient(config) as gh:
+        commits = await gh.get(
+            f"/repos/{owner}/{repo}/commits",
+            params={"sha": sha, "path": path, "per_page": limit},
+        )
+    return [_summarize_commit(commit) for commit in commits]
+
+
+@mcp.tool()
+async def list_issues(
+    owner: str,
+    repo: str,
+    state: str = "open",
+    labels: str | None = None,
+    limit: int = 20,
+) -> list[dict[str, Any]]:
+    """List issues in a repository.
+
+    `state` is one of `open`, `closed`, or `all`. `labels` is an optional
+    comma-separated list of label names to filter by. Note: GitHub's issues
+    endpoint also returns pull requests; check `is_pull_request` on each item.
+    """
+    _require_token()
+    limit = max(1, min(limit, 50))
+    async with GitHubClient(config) as gh:
+        issues = await gh.get(
+            f"/repos/{owner}/{repo}/issues",
+            params={"state": state, "labels": labels, "per_page": limit},
+        )
+    return [_summarize_issue(issue) for issue in issues]
+
+
+@mcp.tool()
+async def get_issue(owner: str, repo: str, issue_number: int) -> dict[str, Any]:
+    """Get a single issue including its full body text."""
+    _require_token()
+    async with GitHubClient(config) as gh:
+        issue = await gh.get(f"/repos/{owner}/{repo}/issues/{issue_number}")
+    summary = _summarize_issue(issue)
+    summary["body"] = issue.get("body")
+    return summary
+
+
+@mcp.tool()
+async def list_pull_requests(
+    owner: str, repo: str, state: str = "open", limit: int = 20
+) -> list[dict[str, Any]]:
+    """List pull requests in a repository.
+
+    `state` is one of `open`, `closed`, or `all`. Returns up to `limit`
+    (max 50) pull requests.
+    """
+    _require_token()
+    limit = max(1, min(limit, 50))
+    async with GitHubClient(config) as gh:
+        pulls = await gh.get(
+            f"/repos/{owner}/{repo}/pulls",
+            params={"state": state, "per_page": limit},
+        )
+    return [_summarize_pull(pull) for pull in pulls]
+
+
+@mcp.tool()
+async def get_pull_request(
+    owner: str, repo: str, pull_number: int
+) -> dict[str, Any]:
+    """Get a single pull request including its body and merge status."""
+    _require_token()
+    async with GitHubClient(config) as gh:
+        pull = await gh.get(f"/repos/{owner}/{repo}/pulls/{pull_number}")
+    summary = _summarize_pull(pull)
+    summary["body"] = pull.get("body")
+    return summary
+
+
+@mcp.tool()
+async def get_pull_request_diff(
+    owner: str, repo: str, pull_number: int, max_chars: int = 20000
+) -> dict[str, Any]:
+    """Get the unified diff for a pull request.
+
+    The diff is truncated to `max_chars` characters to stay within context
+    limits; `truncated` indicates whether anything was cut off.
+    """
+    _require_token()
+    async with GitHubClient(config) as gh:
+        diff = await gh.get_raw(
+            f"/repos/{owner}/{repo}/pulls/{pull_number}",
+            accept="application/vnd.github.diff",
+        )
+    truncated = len(diff) > max_chars
+    return {
+        "pull_number": pull_number,
+        "truncated": truncated,
+        "diff": diff[:max_chars],
+    }
+
+
+@mcp.tool()
+async def search_issues(query: str, limit: int = 10) -> list[dict[str, Any]]:
+    """Search issues and pull requests across GitHub using search qualifiers.
+
+    Example queries: `repo:octocat/hello-world is:open label:bug`,
+    `is:pr author:octocat is:merged`. Returns up to `limit` (max 50) results.
+    """
+    _require_token()
+    limit = max(1, min(limit, 50))
+    async with GitHubClient(config) as gh:
+        result = await gh.get(
+            "/search/issues",
+            params={"q": query, "per_page": limit},
+        )
+    return [_summarize_issue(item) for item in result.get("items", [])]
+
+
+@mcp.tool()
+async def search_code(query: str, limit: int = 10) -> list[dict[str, Any]]:
+    """Search for code across GitHub.
+
+    Example: `addClass in:file language:js repo:jquery/jquery`. A `repo:`,
+    `org:`, or `user:` qualifier is usually required by GitHub's code search.
+    Returns up to `limit` (max 50) matching files.
+    """
+    _require_token()
+    limit = max(1, min(limit, 50))
+    async with GitHubClient(config) as gh:
+        result = await gh.get(
+            "/search/code",
+            params={"q": query, "per_page": limit},
+        )
+    return [
+        {
+            "name": item.get("name"),
+            "path": item.get("path"),
+            "repository": (item.get("repository") or {}).get("full_name"),
+            "html_url": item.get("html_url"),
+        }
+        for item in result.get("items", [])
+    ]
+
+
+# ---------------------------------------------------------------------------
+# write tools (disabled in read-only mode)
+# ---------------------------------------------------------------------------
+
+
+@mcp.tool()
+async def create_issue(
+    owner: str,
+    repo: str,
+    title: str,
+    body: str | None = None,
+    labels: list[str] | None = None,
+) -> dict[str, Any]:
+    """Create a new issue in a repository.
+
+    Disabled when the connector runs in read-only mode. Requires a token with
+    write access to the repository.
+    """
+    _require_token()
+    _require_write()
+    payload: dict[str, Any] = {"title": title}
+    if body is not None:
+        payload["body"] = body
+    if labels:
+        payload["labels"] = labels
+    async with GitHubClient(config) as gh:
+        issue = await gh.post(f"/repos/{owner}/{repo}/issues", json=payload)
+    summary = _summarize_issue(issue)
+    summary["body"] = issue.get("body")
+    return summary
+
+
+@mcp.tool()
+async def add_issue_comment(
+    owner: str, repo: str, issue_number: int, body: str
+) -> dict[str, Any]:
+    """Add a comment to an issue or pull request.
+
+    Disabled when the connector runs in read-only mode. Requires a token with
+    write access to the repository.
+    """
+    _require_token()
+    _require_write()
+    async with GitHubClient(config) as gh:
+        comment = await gh.post(
+            f"/repos/{owner}/{repo}/issues/{issue_number}/comments",
+            json={"body": body},
+        )
+    return {
+        "id": comment.get("id"),
+        "user": (comment.get("user") or {}).get("login"),
+        "html_url": comment.get("html_url"),
+        "created_at": comment.get("created_at"),
+    }
+
+
+def main(argv: list[str] | None = None) -> None:
+    """Console entry point. Selects the transport from CLI args/env."""
+    import argparse
+
+    parser = argparse.ArgumentParser(prog="github-mcp", description=__doc__)
+    parser.add_argument(
+        "--http",
+        action="store_true",
+        help="Serve over streamable HTTP instead of stdio.",
+    )
+    args = parser.parse_args(argv)
+    mcp.run(transport="streamable-http" if args.http else "stdio")
+
+
+if __name__ == "__main__":
+    main()

github_mcp_connector-0.1.0.dist-info/METADATA

@@ -0,0 +1,316 @@
+Metadata-Version: 2.4
+Name: github-mcp-connector
+Version: 0.1.0
+Summary: A Model Context Protocol (MCP) connector for GitHub, for use with Claude.
+Author: winnerlose2026
+License: MIT
+Project-URL: Homepage, https://github.com/winnerlose2026/Github-mcp
+Project-URL: Repository, https://github.com/winnerlose2026/Github-mcp
+Project-URL: Issues, https://github.com/winnerlose2026/Github-mcp/issues
+Keywords: mcp,github,claude,model-context-protocol,connector
+Classifier: Development Status :: 4 - Beta
+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.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=1.2.0
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Dynamic: license-file
+
+# GitHub MCP Connector
+
+A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that
+connects **Claude** to **GitHub**. It exposes a focused set of GitHub REST API
+operations as MCP tools, so Claude (Desktop, Code, or any MCP client) can read
+repositories, browse files and commit history, triage issues, review pull
+requests, and—optionally—open issues and post comments.
+
+It's a small, dependency-light Python package (`mcp` + `httpx`) that you point
+at a GitHub token. It supports both stdio (the default for Claude Desktop/Code)
+and streamable HTTP transports, and works against github.com or GitHub
+Enterprise Server.
+
+## Features
+
+- 🔍 **Search** repositories, issues/PRs, and code with GitHub's query syntax
+- 📦 **Repositories** — metadata, branches, file contents, directory listings
+- 🧾 **Commits** — recent history, optionally filtered to a branch or file path
+- 🐛 **Issues** — list, read, and (optionally) create issues and comments
+- 🔀 **Pull requests** — list, read, and fetch unified diffs
+- 🔒 **Read-only mode** — flip one env var to disable every write tool
+- 🏢 **Enterprise-friendly** — set `GITHUB_API_URL` for GitHub Enterprise Server
+
+## Tools
+
+| Tool | Description | Write |
+|------|-------------|:-----:|
+| `get_authenticated_user` | Identity/health check for the configured token | |
+| `search_repositories` | Search repositories by query | |
+| `get_repository` | Repository metadata | |
+| `list_branches` | Branches with head commit SHAs | |
+| `get_file_contents` | Read a file (decoded) or list a directory | |
+| `list_commits` | Recent commits, optional branch/path filter | |
+| `list_issues` | Issues by state/labels | |
+| `get_issue` | A single issue with full body | |
+| `list_pull_requests` | Pull requests by state | |
+| `get_pull_request` | A single PR with body and merge status | |
+| `get_pull_request_diff` | Unified diff for a PR (truncated) | |
+| `search_issues` | Search issues and PRs across GitHub | |
+| `search_code` | Search code across GitHub | |
+| `create_issue` | Open a new issue | ✅ |
+| `add_issue_comment` | Comment on an issue or PR | ✅ |
+
+Tools marked **Write** are disabled when `GITHUB_MCP_READ_ONLY` is set.
+
+## Requirements
+
+- Python 3.10+
+- A GitHub personal access token. The connector applies **no repository
+  restrictions of its own** — it can reach exactly the repositories your token
+  can, so token scope is what controls access:
+  - **All your repositories (recommended for general use):** create a *classic*
+    PAT with the `repo` scope, or a *fine-grained* PAT whose "Repository access"
+    is set to **All repositories**. This lets the connector see every repo your
+    account can access (public and private).
+  - **Only specific repositories:** use a fine-grained PAT and select just those
+    repos under "Repository access".
+  - **Permissions:** read access is enough for the read tools; to use the write
+    tools (`create_issue`, `add_issue_comment`) the token also needs issue
+    write access (classic: `repo`; fine-grained: *Issues → Read and write*).
+
+## Install from PyPI (recommended)
+
+The connector is published to PyPI as
+[`github-mcp-connector`](https://pypi.org/project/github-mcp-connector/), so you
+can install or run it by name — no clone, no git, no build step. This is the
+most reliable option on Windows, where launching from a git URL requires Git on
+the spawned process's `PATH`.
+
+```bash
+uvx github-mcp-connector            # run on demand with uv (nothing to install)
+pipx run github-mcp-connector       # same, with pipx
+pip install github-mcp-connector    # or install it permanently
+```
+
+Wire it into Claude by pointing the command at the published package:
+
+**Claude Code:**
+```bash
+claude mcp add-json github '{
+  "command": "uvx",
+  "args": ["github-mcp-connector"],
+  "env": { "GITHUB_TOKEN": "github_pat_your_token_here" }
+}'
+```
+
+**Claude Desktop** (`claude_desktop_config.json`):
+```json
+{
+  "mcpServers": {
+    "github": {
+      "command": "uvx",
+      "args": ["github-mcp-connector"],
+      "env": { "GITHUB_TOKEN": "github_pat_your_token_here" }
+    }
+  }
+}
+```
+
+On Windows, use the full path to `uvx.exe` (run `where.exe uvx` to find it), e.g.
+`C:\\Users\\you\\.local\\bin\\uvx.exe`.
+
+## Quick start (no clone, no venv)
+
+If the package isn't published yet (or you want to track an unreleased commit),
+`uvx` can also fetch, build, and run the connector straight from GitHub. This
+path requires Git to be available to the process that launches it.
+
+**Claude Code — one command:**
+
+```bash
+claude mcp add-json github '{
+  "command": "uvx",
+  "args": ["--from", "git+https://github.com/winnerlose2026/Github-mcp.git", "github-mcp"],
+  "env": { "GITHUB_TOKEN": "github_pat_your_token_here" }
+}'
+```
+
+Add `--scope user` to make it available in every project. Verify with
+`claude mcp list` (should show `github` connected).
+
+**Claude Code — project-scoped, shareable:** this repo ships a [`.mcp.json`](.mcp.json)
+that reads `GITHUB_TOKEN` from your environment. Drop the same file in any project
+(or copy it from here), export your token, and Claude Code auto-detects it:
+
+```bash
+export GITHUB_TOKEN=github_pat_your_token_here
+claude   # prompts once to approve the project MCP server
+```
+
+**Claude Desktop:** point the `command` at `uvx` so there's no interpreter path to
+manage:
+
+```json
+{
+  "mcpServers": {
+    "github": {
+      "command": "uvx",
+      "args": ["--from", "git+https://github.com/winnerlose2026/Github-mcp.git", "github-mcp"],
+      "env": { "GITHUB_TOKEN": "github_pat_your_token_here" }
+    }
+  }
+}
+```
+
+**Prefer pipx?** `pipx run --spec git+https://github.com/winnerlose2026/Github-mcp.git github-mcp`
+works the same way; use that as the `command`/`args` instead.
+
+## Installation (from source)
+
+For development, or if you don't use `uv`/`pipx`:
+
+```bash
+git clone https://github.com/winnerlose2026/Github-mcp.git
+cd Github-mcp
+python -m venv .venv && source .venv/bin/activate
+pip install -e .
+```
+
+Or, without installing, from the repo root:
+
+```bash
+pip install -r requirements.txt
+python -m github_mcp
+```
+
+## Configuration
+
+All configuration comes from environment variables (see [`.env.example`](.env.example)):
+
+| Variable | Required | Default | Description |
+|----------|:--------:|---------|-------------|
+| `GITHUB_TOKEN` | yes | — | GitHub token. `GITHUB_PERSONAL_ACCESS_TOKEN` and `GH_TOKEN` are also accepted. |
+| `GITHUB_API_URL` | no | `https://api.github.com` | API root; set for GitHub Enterprise Server (e.g. `https://ghe.example.com/api/v3`). |
+| `GITHUB_MCP_READ_ONLY` | no | `false` | When truthy, disables all write tools. |
+| `GITHUB_MCP_TIMEOUT` | no | `30` | Per-request timeout in seconds. |
+| `GITHUB_MCP_USER_AGENT` | no | `github-mcp-connector` | `User-Agent` header sent to GitHub. |
+
+## Connecting to Claude (from-source install)
+
+If you installed from source (above) instead of using `uvx`/`pipx`, configure
+the client to run the package directly.
+
+### Claude Desktop
+
+Add the server to `claude_desktop_config.json` (Settings → Developer → Edit
+Config):
+
+```json
+{
+  "mcpServers": {
+    "github": {
+      "command": "python",
+      "args": ["-m", "github_mcp"],
+      "env": {
+        "GITHUB_TOKEN": "ghp_your_token_here"
+      }
+    }
+  }
+}
+```
+
+Use the absolute path to the Python interpreter from the virtualenv where you
+installed the package (e.g. `/path/to/Github-mcp/.venv/bin/python`), or the
+`github-mcp` console script directly. Restart Claude Desktop after editing.
+
+### Claude Code
+
+```bash
+claude mcp add github \
+  --env GITHUB_TOKEN=ghp_your_token_here \
+  -- python -m github_mcp
+```
+
+### Streamable HTTP
+
+To run as a standalone HTTP server instead of stdio:
+
+```bash
+GITHUB_TOKEN=ghp_your_token_here python -m github_mcp --http
+```
+
+## Example prompts
+
+Once connected, you can ask Claude things like:
+
+- "What's the open PR backlog on `owner/repo`?"
+- "Read `README.md` from the default branch of `owner/repo` and summarize it."
+- "Show me the diff for PR #42 and summarize the risky parts."
+- "Open an issue titled 'Flaky test in CI' with these reproduction steps…"
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+The test suite mocks the GitHub API with `httpx.MockTransport`, so it runs
+fully offline and makes no network calls.
+
+## Releasing (maintainers)
+
+Publishing is automated via GitHub Actions
+([`.github/workflows/publish.yml`](.github/workflows/publish.yml)) using PyPI
+**Trusted Publishing** (OIDC) — no API tokens are stored anywhere.
+
+**One-time PyPI setup** (before the first release):
+
+1. Sign in at [pypi.org](https://pypi.org) and go to **Your projects → Publishing**
+   (or **Account → Publishing** for a project that doesn't exist yet).
+2. Add a **pending publisher** with:
+   - PyPI Project Name: `github-mcp-connector`
+   - Owner: `winnerlose2026`
+   - Repository: `Github-mcp`
+   - Workflow name: `publish.yml`
+   - Environment name: `pypi`
+3. (Recommended) In the GitHub repo, create an **Environment** named `pypi`
+   (Settings → Environments) so the publish job is gated.
+
+**Cutting a release:**
+
+1. Bump `version` in `pyproject.toml`, commit, and merge to `main`.
+2. Tag and publish a GitHub Release (e.g. `v0.1.0`). Publishing the release
+   triggers the workflow, which builds the sdist + wheel, runs `twine check`,
+   and uploads to PyPI.
+3. Confirm it's live: `uvx github-mcp-connector@latest --help`.
+
+Until the first release is published, install via the
+[git-based quick start](#quick-start-no-clone-no-venv) instead.
+
+## Security notes
+
+- The connector only has the access your token grants. A broad token (`repo`
+  scope / all repositories) gives Claude reach across every repo your account
+  can touch — convenient, but treat the token like the credential it is. Prefer
+  a fine-grained, repo-limited token if you only need a few repositories.
+- Run with `GITHUB_MCP_READ_ONLY=true` when you only need read access; this is
+  enforced server-side, before any write request is sent to GitHub. This pairs
+  well with a broad-access token: full visibility, no write risk.
+- Never commit your token. `.env` is git-ignored; `.env.example` is the
+  template to copy.
+
+## License
+
+[MIT](LICENSE)

github_mcp_connector-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+github_mcp/__init__.py,sha256=BkynbNaLysjU28VDDaNfFzZeUk3tJxD-mBNar_ulWGE,332
+github_mcp/__main__.py,sha256=p2LRgzcQfYXSOy1lG-RViI1WSPmqF1bXvxaT_8-oork,130
+github_mcp/client.py,sha256=JfKCk5lz5Tw8w-dshUaEJbItENidtDQwFTAyQukt2Kw,4586
+github_mcp/config.py,sha256=dnHvtQaampb41js6VkK_iCa1bs6fywsvGhzsipU0gQE,1679
+github_mcp/server.py,sha256=F6ie5bYnZxCErRzsNr-uyTeOrKS6x1cQ7ZMJHvsWWsA,15289
+github_mcp_connector-0.1.0.dist-info/licenses/LICENSE,sha256=9hlM7Wg0Oxyq7Zu5VoT_Fj81Ng6IAxjXYg9_AOBxBJ8,1071
+github_mcp_connector-0.1.0.dist-info/METADATA,sha256=uMWo_OecgPWi2PlvMkrYhugGrqcscj-QL4UtV30vBSg,11422
+github_mcp_connector-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+github_mcp_connector-0.1.0.dist-info/entry_points.txt,sha256=_gpMCjdQqpecWEuktKFCMPRF427yhKlLSDVei-43N5I,100
+github_mcp_connector-0.1.0.dist-info/top_level.txt,sha256=Oz7KcY8SwRmG0rRos2vB8LycqcG5vapSkveK8aqQi0Q,11
+github_mcp_connector-0.1.0.dist-info/RECORD,,

github_mcp_connector-0.1.0.dist-info/WHEEL

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

github_mcp_connector-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+github-mcp = github_mcp.server:main
+github-mcp-connector = github_mcp.server:main

github_mcp_connector-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 winnerlose2026
+
+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.

github_mcp_connector-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+github_mcp