GitHub Profile MCP Server

April 10, 2025 ยท View on GitHub

A Model Context Protocol (MCP) server that provides access to GitHub profile data, repositories information, and other GitHub-related features through a simple API. This tool allows AI assistants to fetch GitHub profile information, repositories, languages, and more.

Features

  • Get detailed user profile information
  • Retrieve a user's top repositories sorted by stars, update time, or creation date
  • Analyze a user's top programming languages
  • Search for repositories by topic/keyword

Installation

  1. Clone the repository:

    git clone https://github.com/yourusername/github-profile-mcp.git
cd github-profile-mcp

  2. Install dependencies:

    npm install

  3. Create a .env file from the example:

    cp .env.example .env

  4. Add your GitHub personal access token to the .env file:

    GITHUB_TOKEN=your-github-token-here

  5. Build the TypeScript code:

    npm run build

Usage

Start the MCP server:

npm start

MCP Server Config for Claude/VS Code/Windsurf/...

Note: Ensure that the installation steps are complete before this step

{
  "mcpServers": {
    "github-profile-mcp": {
      "command": "node",
      "args": ["path-to-repo-directory\\build\\index.js"],
      "env": {
        "GITHUB_TOKEN": "your-github-token"
      }
    }
  }
}

The server runs as a stdio-based MCP server, allowing AI assistants to connect and use its tools.

Available Tools

get-user-profile

Fetches detailed information about a GitHub user profile.

Parameters:

  • username: GitHub username (required)
  • token: GitHub personal access token (optional)

Example response:

{
  "login": "octocat",
  "name": "The Octocat",
  "bio": "I'm the GitHub mascot!",
  "company": "GitHub",
  "location": "San Francisco",
  "blog": "https://github.blog",
  "email": "octocat@github.com",
  "publicRepos": 8,
  "publicGists": 8,
  "followers": 3000,
  "following": 9,
  "createdAt": "2011-01-25T18:44:36Z",
  "updatedAt": "2023-01-22T12:17:28Z"
}

get-top-repositories

Retrieves a user's top repositories based on specified sort criteria.

Parameters:

  • username: GitHub username (required)
  • count: Number of repositories to return (1-10, default: 5)
  • sort: Sort criteria ("stars", "updated", "created", default: "stars")
  • token: GitHub personal access token (optional)

Example response:

[
  {
    "name": "hello-world",
    "description": "My first repository on GitHub!",
    "stars": 80,
    "forks": 34,
    "language": "JavaScript",
    "url": "https://github.com/octocat/hello-world",
    "createdAt": "2011-01-26T19:01:12Z",
    "updatedAt": "2023-01-20T11:05:00Z",
    "topics": ["beginner", "sample"]
  }
]

get-top-languages

Analyzes a user's repositories to determine their most used programming languages.

Parameters:

  • username: GitHub username (required)
  • token: GitHub personal access token (optional)

Example response:

{
  "totalRepos": 50,
  "languages": [
    {
      "language": "JavaScript",
      "count": 20,
      "percentage": 40
    },
    {
      "language": "TypeScript",
      "count": 15,
      "percentage": 30
    },
    {
      "language": "Python",
      "count": 10,
      "percentage": 20
    }
  ]
}

search-repositories-by-topic

Searches for popular repositories by topic or keyword.

Parameters:

  • topic: Topic/keyword to search for (required)
  • count: Number of repositories to return (1-10, default: 5)
  • token: GitHub personal access token (optional)

Example response:

{
  "total_count": 12345,
  "items": [
    {
      "name": "react",
      "full_name": "facebook/react",
      "description": "A JavaScript library for building user interfaces",
      "stars": 200000,
      "forks": 41000,
      "language": "JavaScript",
      "url": "https://github.com/facebook/react",
      "owner": {
        "login": "facebook",
        "url": "https://github.com/facebook"
      }
    }
  ]
}

GitHub API Rate Limits

Without authentication, the GitHub API has a rate limit of 60 requests per hour. With a personal access token, this increases to 5,000 requests per hour. It's recommended to always use a token for better performance.

Development

This project is written in TypeScript and uses:

License

MIT License