# personal-github-mcp

A minimal, personal MCP server that gives Claude (via Claude Code or Claude
Desktop) full read/write access to the GitHub REST API, using your own
Personal Access Token (PAT) — no third-party app permissions, no 403s from
a shared connector's scopes.

It exposes **one tool**, `github_request`, that can call *any* GitHub REST
API endpoint with any HTTP method (`GET`, `POST`, `PATCH`, `PUT`, `DELETE`).
That covers everything: creating issues, commenting, merging PRs, creating/
updating files, branches, releases, labels, workflows — the full API at
https://docs.github.com/en/rest.

## 1. Create a GitHub Personal Access Token

1. Go to https://github.com/settings/tokens?type=beta (fine-grained token,
   recommended) or https://github.com/settings/tokens (classic).
2. **Fine-grained token**: scope it to your account, pick "Only select
   repositories" (or all, if you want), and under **Repository permissions**
   grant at least:
   - Contents: Read and write
   - Issues: Read and write
   - Pull requests: Read and write
   - Metadata: Read-only (required)
3. **Classic token**: just check the `repo` scope.
4. Copy the token — you won't see it again.

## 2. Install dependencies

```bash
cd github-mcp-server
npm install
```

## 3. Configure your MCP client

### Claude Code

Add to your Claude Code MCP config (`~/.claude.json` or via `claude mcp add`):

```bash
claude mcp add personal-github -- node /absolute/path/to/github-mcp-server/index.js
```

Then set the token as an environment variable before launching, or add it
directly to the config's `env` block:

```json
{
  "mcpServers": {
    "personal-github": {
      "command": "node",
      "args": ["/absolute/path/to/github-mcp-server/index.js"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}
```

### Claude Desktop

Edit your `claude_desktop_config.json` (Settings → Developer → Edit Config)
and add the same `mcpServers` block as above, then restart Claude Desktop.

## 4. Use it

Once connected, ask Claude things like:

- "Create an issue in neural-shubh/dark-fleet-detection titled X with body Y"
- "List my open pull requests across all repos"
- "Update the README.md in neural-shubh/mediscan-ai"

Claude will call `github_request` with the right method/path/body — e.g.
`POST /repos/neural-shubh/dark-fleet-detection/issues` with
`{"title": "...", "body": "..."}`.

## Security notes

- The token lives only in your local MCP config / environment — it's never
  sent anywhere except `api.github.com`.
- Scope the token as narrowly as you're comfortable with (fine-grained,
  select repos only) since this server will honor whatever the token allows.
- This server does not implement any allow/deny tool policy of its own —
  the token's scopes are the only guardrail. If you want to restrict it
  further (e.g. read-only, or single-repo-only) that's easy to add — just
  ask.