GitHub Assistant MCP Server

A lightweight Model Context Protocol (MCP) server that connects Claude (or any MCP-compatible client) directly to your GitHub account — letting Claude answer questions like "How many commits did I make today?" by calling the GitHub REST API on your behalf.

Architecture / Flow

flowchart LR
    A[" User"] -->|"Ask: How many commits today?"| B[" Claude (MCP Client)"]
    B -->|"stdio transport"| C["⚙️ MCP Server\n(github-assistant)"]
    C -->|"registerTool: getMyTodayCommits"| D{"GitHub REST API"}
    D -->|"GET /user"| E[" Authenticated user"]
    D -->|"GET /user/repos"| F[" List of repositories"]
    D -->|"GET /repos/:owner/:repo/commits"| G[" Commits per repo (today)"]
    E --> C
    F --> C
    G --> C
    C -->|"JSON: totalCommits + repositories"| B
    B -->|"Formatted answer"| A

In short:

1. You ask Claude a question in natural language.

2. Claude recognizes it matches the getMyTodayCommits tool and invokes the MCP server over stdio.

3. The server authenticates with your GITHUB_TOKEN, fetches your GitHub username, lists your repositories, then queries commits made today across all of them.

4. The aggregated result (total commits + per-repo breakdown) is returned to Claude, which turns it into a natural-language answer for you.

Related MCP server: GitHub MCP Server

Features

• Secure token-based GitHub authentication (via .env, never hardcoded)

• Aggregates today's commit count across all your repositories

• Built on the official @modelcontextprotocol/sdk

• Works with any MCP-compatible client (Claude Desktop, Claude Code, etc.)

• Zero database, zero server hosting — runs locally over stdio

Project Structure

github-assistant-mcp/
├── src/
│   └── index.ts          # MCP server entry point (tool registration + logic)
├── .env                   # Your local GitHub token (not committed)
├── .env.example           # Template for required env vars
├── package.json
├── tsconfig.json
└── README.md

Getting Started

1. Fork & Clone

# Fork this repo on GitHub first, then:
git clone https://github.com/<your-username>/github-assistant-mcp.git
cd github-assistant-mcp

2. Install dependencies

npm install

3. Create a GitHub Personal Access Token

1. Go to GitHub → Settings → Developer settings → Personal access tokens → Fine-grained tokens

2. Generate a new token with at least:

   • Contents: Read-only

   • Metadata: Read-only

3. Copy the generated token.

4. Configure environment variables

cp .env.example .env

# .env
GITHUB_TOKEN=ghp_your_token_here

Never commit your .env file. Make sure it's listed in .gitignore.

5. Build the project

npm run build

This compiles src/index.ts into a runnable JS entry point (e.g. dist/index.js).

6. Run it standalone (optional sanity check)

node dist/index.js

You should see:

GitHub MCP SERVER STARTED

The server is now listening on stdio, waiting for an MCP client to connect.

Connecting to Claude

Claude Desktop

Edit your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add an entry under mcpServers:

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

Restart Claude Desktop. You should see github-assistant listed under the 🔌 connectors/tools icon.

Claude Code / CLI

claude mcp add github-assistant -- node /absolute/path/to/github-assistant-mcp/dist/index.js

Available Tools

Example response:

{
  "totalCommits": 7,
  "repositories": {
    "my-portfolio": 3,
    "mcp-experiments": 4
  }
}

Forking & Extending

Want to add your own tools (e.g. getOpenPullRequests, getStarredRepos)? The pattern is simple:

server.registerTool(
  "yourToolName",
  { description: "What this tool does" },
  async () => {
    // 1. Call GitHub (or any) API
    // 2. Shape the response
    return {
      content: [{ type: "text", text: JSON.stringify(result) }],
    };
  }
);

Steps to contribute:

1. Fork this repository

2. Create a feature branch: git checkout -b feature/your-tool-name

3. Add your tool inside src/index.ts (or split into src/tools/*.ts as it grows)

4. Test locally by running the compiled server and connecting it to Claude Desktop/Code

5. Commit and open a Pull Request 🎉

⚠️ Known Limitations

• The repository owner in the commit-fetch URL is currently hardcoded (JokkimDoras) — replace this with the dynamically fetched username variable so the tool works for any forked user.

• Only checks the authenticated user's own repos (/user/repos) — doesn't cover commits made to repos you've contributed to but don't own.

• No pagination handling beyond the first 100 repos.

📄 License

MIT — free to use, fork, and modify.