🚀 GitHub Activity MCP Server

An MCP (Model Context Protocol) server built with FastMCP and PyGithub that connects AI assistants to GitHub — search repos, manage issues & PRs, analyze contributions, and more.

What is MCP? The Model Context Protocol is an open standard that lets AI assistants connect to external data and tools through a unified interface. Think of it as "USB-C for AI".

---

✨ Features

This server exposes 13 tools, 3 resource providers, and 3 prompt templates — covering all three MCP primitives.

🔧 Tools (Model-Controlled)

Actions the AI can take autonomously:

Tool	Description
search_repositories	Search GitHub repos by query, language, stars
get_repository	Get detailed repo info (stars, forks, topics, etc.)
get_file_contents	Read any file from a repo
list_commits	List recent commits with filters
list_issues	List issues with state/label/assignee filters
get_issue	Get full issue details + comments
create_issue	Create a new issue
add_issue_comment	Comment on an issue
list_pull_requests	List PRs with state/branch filters
get_pull_request	Get PR details + merge status
get_pull_request_diff	View PR code changes
get_user_profile	Get a user's public profile
list_user_repos	List a user's repositories

📦 Resources (Application-Controlled)

Contextual data the AI can read:

Resource URI	Description
github://repo/{owner}/{repo}/readme	Repository README (markdown)
github://repo/{owner}/{repo}/tree	Full file tree listing
github://repo/{owner}/{repo}/languages	Language breakdown with percentages

💬 Prompts (User-Triggered)

Pre-built workflow templates:

Prompt	Description
analyze-repo	Comprehensive repository analysis
review-pr	Code review with best practices
issue-triage	Categorize and prioritize open issues

---

🏗️ Architecture

graph LR
    A[AI Assistant] <-->|MCP Protocol| B[GitHub MCP Server]
    B <-->|REST API| C[GitHub API]

    subgraph "MCP Server (FastMCP)"
        B --> D[Tools]
        B --> E[Resources]
        B --> F[Prompts]
    end

    subgraph "Tools"
        D --> D1[Repos]
        D --> D2[Issues]
        D --> D3[Pull Requests]
        D --> D4[Users]
    end

---

🚀 Quick Start

Prerequisites

• Python ≥ 3.10
• GitHub Personal Access Token (optional, but recommended for higher rate limits)

Installation

# Clone the repository
git clone https://github.com/YOUR_USERNAME/github-mcp-server.git
cd github-mcp-server

# Install dependencies
pip install fastmcp PyGithub

Set up your GitHub Token (Optional)

Create a Personal Access Token with repo and read:user scopes:

# Linux/macOS
export GITHUB_TOKEN=ghp_your_token_here

# Windows (PowerShell)
$env:GITHUB_TOKEN = "ghp_your_token_here"

Note: Without a token, you're limited to 60 API requests/hour. With a token, you get 5,000/hour.

Run the Server

# Run directly
fastmcp run src/server.py

# Or with Python
python -m src.server

Test with FastMCP Dev Mode

fastmcp dev src/server.py

---

⚙️ Configuration

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, or %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "github": {
      "command": "fastmcp",
      "args": ["run", "src/server.py"],
      "cwd": "/absolute/path/to/github-mcp-server",
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

Cursor

Add to your Cursor MCP config (.cursor/mcp.json in your project or global config):

{
  "mcpServers": {
    "github": {
      "command": "fastmcp",
      "args": ["run", "src/server.py"],
      "cwd": "/absolute/path/to/github-mcp-server",
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

VS Code (GitHub Copilot)

Add to your VS Code settings (.vscode/settings.json):

{
  "mcp": {
    "servers": {
      "github": {
        "command": "fastmcp",
        "args": ["run", "src/server.py"],
        "cwd": "/absolute/path/to/github-mcp-server",
        "env": {
          "GITHUB_TOKEN": "ghp_your_token_here"
        }
      }
    }
  }
}

---

📁 Project Structure

github-mcp-server/
├── src/
│   ├── __init__.py
│   ├── server.py             # FastMCP server instance & entry point
│   ├── github_client.py      # PyGithub client wrapper & error handling
│   ├── resources.py          # Resource providers (README, tree, languages)
│   ├── prompts.py            # Prompt templates (analyze, review, triage)
│   └── tools/
│       ├── __init__.py
│       ├── repos.py          # Repository tools (search, get, file contents, commits)
│       ├── issues.py         # Issue tools (list, get, create, comment)
│       ├── pulls.py          # Pull request tools (list, get, diff)
│       └── users.py          # User tools (profile, repos)
├── pyproject.toml
├── README.md
├── LICENSE
└── .gitignore

---

🛠️ Tech Stack

Technology	Purpose
FastMCP	High-level MCP server framework
PyGithub	GitHub REST API client
Model Context Protocol	The open standard for AI-tool integration

---

🤝 Contributing

Contributions are welcome! Here's how:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

---

<p align="center"> Built with ❤️ using FastMCP and the Model Context Protocol </p>