github-mcp 1.1.0__py3-none-any.whl

github_mcp-1.1.0.dist-info/METADATA

@@ -0,0 +1,193 @@
+Metadata-Version: 2.4
+Name: github-mcp
+Version: 1.1.0
+Summary: Local GitHub MCP server exposing GitHub REST API via FastMCP stdio transport
+License: MIT License
+         
+         Copyright (c) 2026 Lucas
+         
+         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.
+License-File: LICENSE
+Keywords: github,mcp,fastmcp,stdio,rest api,search
+Author: Lucas Waetzig
+Author-email: development@waetzig.net
+Requires-Python: >=3.12
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries
+Requires-Dist: httpx (>=0.28.1,<0.29.0)
+Requires-Dist: mcp[cli] (>=1.0.0)
+Requires-Dist: pydantic (>=2.13.4,<3.0.0)
+Project-URL: Documentation, https://personal-public-packages.gitlab.io/github-mcp
+Project-URL: Homepage, https://github.com/LWaetzig/github-mcp
+Project-URL: Issues, https://github.com/LWaetzig/github-mcp/issues
+Project-URL: Repository, https://github.com/LWaetzig/github-mcp
+Description-Content-Type: text/markdown
+
+# github-mcp
+
+An MCP (Model COntext Protocol) server that gives AI assistants direct access to GitHub. Exposing ~22 GitHub REST tools
+covering repos, files, issues, pull requests, as well as searching.
+
+## Table of Contents
+
+1. [Features](#features)
+2. [Installation](#installation)
+3. [Usage]()
+4. [Contributing]()
+
+## Features
+
+A single stdio MCP server (built on [FastMCP](https://github.com/modelcontextprotocol/python-sdk)) exposing **23 GitHub REST tools** grouped into four areas:
+
+- **Repositories & files** — `github_list_repos`, `github_get_repo`, `github_list_branches`, `github_list_commits`, `github_get_file_contents`, `github_list_directory`, `github_create_or_update_file`, `github_create_branch`
+- **Issues** — `github_list_issues`, `github_get_issue`, `github_create_issue`, `github_update_issue`, `github_add_issue_comment`
+- **Pull requests** — `github_list_pull_requests`, `github_get_pull_request`, `github_create_pull_request`, `github_merge_pull_request`, `github_add_pr_comment`
+- **Search** — `github_search_repositories`, `github_search_code`, `github_search_issues`, `github_search_users`, `github_search_commits`
+
+Under the hood:
+
+- **Async HTTP** via a shared, lazily-initialised `httpx.AsyncClient` against the pinned GitHub API version (`2022-11-28`).
+- **Automatic pagination** — list endpoints follow the `Link: rel="next"` header up to a configurable item cap.
+- **Typed inputs** — every tool validates its arguments with Pydantic models.
+- **Actionable errors** — common GitHub failures (401, 403/rate-limit with reset time, 404, 409, 422, timeouts) are translated into clear, human-readable messages.
+- **Flexible auth** — reads a fine-grained PAT from `GITHUB_TOKEN`, falling back to `GITHUB_PAT`.
+
+## Installation
+
+### Prerequisites
+
+- `Python 3.12` or later
+- Dependencies `mcp[cli]>=1.0.0`, `httpx>=0.27.0`, `pydantic>=2.0.0` (see [pyproject.toml](pyproject.toml)) (project uses `poetry` for dependency management)
+
+
+### Install from PyPi
+
+```bash
+pip install github-mcp
+
+# or using poetry
+poetry add github-mcp
+```
+
+### Build from source
+
+```bash
+git clone https://github.com/LWaetzig/github-mcp.git
+cd github-mcp
+pip install -e .
+```
+
+## Usage
+
+- Detailed documentation about single tools can be found this [sphinx documentation]()
+
+### Prerequisites
+
+#### Create a fine-grained Personal Access Token (PAT)
+
+1. Go to **GitHub -> Settings -> Developer settings -> Personal access tokens -> Fine-grained tokens** (direct link: <https://github.com/settings/tokens?type=beta>)
+2. Generate new token
+3. Set **Resource owner** and **Repository access** as appropriate
+4. Grant these **Repository permissions** (minimum for full read + write):
+
+| Permission        | Access level   | Used by tools                                                                                                                              |
+| ----------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Metadata**      | Read-only      | All tools                                                                                                                                  |
+| **Contents**      | Read and write | `github_get_file_contents`, `github_list_directory`, `github_list_commits`, `github_create_or_update_file`, `github_create_branch`         |
+| **Issues**        | Read and write | `github_list_issues`, `github_get_issue`, `github_create_issue`, `github_update_issue`, `github_add_issue_comment`                         |
+| **Pull requests** | Read and write | `github_list_pull_requests`, `github_get_pull_request`, `github_create_pull_request`, `github_merge_pull_request`, `github_add_pr_comment` |
+
+> **Read-only subset**: grant only **Read-only** access to Contents, Issues, Pull requests, and Metadata if you don't need write tools.
+
+
+```bash
+export GITHUB_TOKEN=github_pat_...
+```
+
+Or copy `.env.example` -> `.env` and fill in the token (load with `source .env`).
+
+
+### Integrating with Claude Desktop
+
+Add the server to your Claude Desktop configuration:
+
+| Platform | Path |
+|---|---|
+| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
+
+Add the `github` entry under `mcpServers`, replacing the path with the absolute path to your clone:
+
+```json
+{
+  "mcpServers" : {
+    "github" : {
+      "command" : "python",
+      "args" : ["-m", "github-mcp"],
+      "env" : {
+        "GITHUB_TOKEN" : "github_pat_..."
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. You should see the github tools available int he tool picker.
+
+### Integration with Other MCP Clients
+
+Any MCP client (e.g. Cline, GitHub Copilot, or custm tools) can use this server.
+Configuration depends on your assistant, in most cases there is a `config` to change.
+
+
+## Contribution
+
+Contributions are welcome! Please:
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/your-feature`)
+3. Commit your changes with clear messages
+4. Push to your fork
+5. Open a pull request
+
+
+### Live testing with MCP Inspector (requires a real token)
+
+```bash
+GITHUB_TOKEN=... 
+npx @modelcontextprotocol/inspector 
+uv run github-mcp
+```
+
+Then call `github_search_repositories` (q=`"mcp language:python"`) or `github_get_repo` (owner=`"modelcontextprotocol"`, repo=`"python-sdk"`) to verify auth,
+pagination, and formatting end-to-end.
+
+
+## Upcoming Features
+
+- **Projects v2**: Requires GitHub's GraphQL API (`/graphql`). Add a `graphql_client.py` alongside `client.py` and a new `tools/projects.py` module.
+- **Actions**: Also REST-based but with many endpoints. Add `tools/actions.py` importing from `client.py`.

github_mcp-1.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+github_mcp/__init__.py,sha256=-cx-hrMID_2q5ixVhAayshit9UnVB3wjJALSpI6hKs8,104
+github_mcp/app.py,sha256=GBqVSTPpz43GYQ59r-T8biCz4Brm5s9wdxD_Kcn_eMA,68
+github_mcp/client.py,sha256=LMBNjydU2Y7vStjFYirIE-WhkSpcJB-WclLunAJ0xNc,8763
+github_mcp/formatting.py,sha256=oQXiNovgbrw7YbFgwTu_rT8-beSRAFHpn9TOmuKyb2c,3917
+github_mcp/server.py,sha256=vxOhwJDuES8iGto2K9wtRnAu-r2XZfhuiu6E331vhQA,453
+github_mcp/tools/__init__.py,sha256=1Oeoii5RzMLNd7cLq4Z6ydgk-yQ9SJqpTejYvbs3tOU,89
+github_mcp/tools/issues.py,sha256=CzrJEEmZ-xUsYzqXWvp6-B1-2tYbNcy6T2_0V_7-z5E,14447
+github_mcp/tools/pulls.py,sha256=AG9udxovrmnUjSdKEyzgW5qjTD5aPquHYyFyQS5OhRs,15567
+github_mcp/tools/repos.py,sha256=m7qWWmtBWrLm3jn5iSbnmsa768cEyw5-covAIlXaDzo,23991
+github_mcp/tools/search.py,sha256=6VyvRG7wIPrjimIjkuc6vJBtAVF7qiK7clmfZiSWNvI,17932
+github_mcp-1.1.0.dist-info/METADATA,sha256=UY13nfkjt9cxXQIivwGff4mur4OhOx9ACcU1kzZJOf0,8233
+github_mcp-1.1.0.dist-info/WHEEL,sha256=kJCRJT_g0adfAJzTx2GUMmS80rTJIVHRCfG0DQgLq3o,88
+github_mcp-1.1.0.dist-info/entry_points.txt,sha256=hgmRd9ToUUhH7k07RC2X4yuG1H9MOBhM_jUUAAgWkuc,59
+github_mcp-1.1.0.dist-info/licenses/LICENSE,sha256=KQfV6Cz2Um8tbLZEQPiOXbJF76RE5fJC_soO1-otIKI,1062
+github_mcp-1.1.0.dist-info/RECORD,,

github_mcp-1.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.3.1
+Root-Is-Purelib: true
+Tag: py3-none-any

github_mcp-1.1.0.dist-info/entry_points.txt

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

github_mcp-1.1.0.dist-info/licenses/LICENSE

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