@mcp/github-search

Comprehensive GitHub Search MCP server for code search, repository discovery, and issue tracking.

Overview

This MCP server provides powerful GitHub search capabilities by leveraging the official GitHub REST API via Octokit. It enables intelligent code search, repository discovery, issue tracking, and pull request management directly through the Model Context Protocol.

Features

Search Tools

• search_code - Search for code across all GitHub repositories
• search_repositories - Find repositories by name, description, topics, or content
• search_issues - Search issues and pull requests across repositories
• search_users - Find GitHub users by username, email, or name
• search_commits - Search commits within repositories

Repository Tools

• get_repository - Get detailed repository information
• list_repositories - List repositories for a user or organization
• get_repository_contents - Get contents of a repository directory or file
• get_repository_readme - Fetch the README from a repository

Issue & PR Tools

• get_issue - Get detailed issue information
• list_issues - List issues in a repository
• create_issue - Create a new issue
• get_pull_request - Get detailed PR information
• list_pull_requests - List PRs in a repository

Code Tools

• get_file_content - Get raw content of any file
• get_commit_info - Get detailed commit information
• list_branches - List branches in a repository

Installation

cd /MCP/packages/github-search
bun install

Configuration

The GitHub Search MCP server supports multiple authentication methods with the following priority:

1. CLI Arguments (Highest Priority)

# Direct token specification
mcp-github-search --github-token ghp_xxxxxxxxxxxx

# Or using Doppler
mcp-github-search --doppler-project my-project --doppler-config prd

2. Doppler Integration

Fetch the GitHub token from a Doppler project:

# Using default config (prd)
mcp-github-search --doppler-project my-project

# Using custom config
mcp-github-search --doppler-project my-project --doppler-config dev

The server executes: doppler secrets get GITHUB_TOKEN --project <project> --config <config> --plain

3. Environment Variable (Fallback)

# Required: GitHub Personal Access Token
export GITHUB_TOKEN="ghp_..."

Configuration Priority

1. CLI argument --github-token (highest priority)
2. Doppler --doppler-project (with optional --doppler-config)
3. Environment variable GITHUB_TOKEN (fallback)

GitHub Token Permissions:

• public_repo - For public repositories
• repo - For private repositories (full control)
• read:org - For organization access

Usage

As MCP Server

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "github-search": {
      "command": "node",
      "args": ["/path/to/@mcp/github-search/dist/index.js"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      },
      "description": "GitHub search and repository management"
    }
  }
}

Or with CLI arguments:

{
  "mcpServers": {
    "github-search": {
      "command": "node",
      "args": ["/path/to/@mcp/github-search/dist/index.js", "--github-token", "ghp_your_token_here"],
      "description": "GitHub search and repository management"
    }
  }
}

Or with Doppler:

{
  "mcpServers": {
    "github-search": {
      "command": "node",
      "args": ["/path/to/@mcp/github-search/dist/index.js", "--doppler-project", "my-project", "--doppler-config", "prd"],
      "description": "GitHub search and repository management"
    }
  }
}

Programmatic Usage

import { GitHubSearchClient } from "./client.js";

// Initialize the client
const client = new GitHubSearchClient({
  token: process.env.GITHUB_TOKEN,
});

// Search for code
const codeResults = await client.searchCode({
  query: "useState in:file language:typescript",
  perPage: 10,
});

// Find repositories
const repos = await client.searchRepositories({
  query: "topic:mcp-server stars:>10",
  sort: "stars",
  order: "desc",
});

// Get repository details
const repo = await client.getRepository({
  owner: "microsoft",
  repo: "typescript",
});

// Search issues
const issues = await client.searchIssues({
  query: "label:bug state:open",
  owner: "facebook",
  repo: "react",
});

// Get file content
const content = await client.getFileContent({
  owner: "vercel",
  repo: "next.js",
  path: "README.md",
});

Architecture

@mcp/github-search
├── src/
│   ├── index.ts        # MCP server entry point
│   ├── client.ts       # GitHub API client (Octokit wrapper)
│   ├── search.ts       # Search-specific implementations
│   └── types.ts        # TypeScript types and Zod schemas
├── dist/               # Compiled JavaScript
├── package.json
├── tsconfig.json
└── README.md

Tool Definitions

search_code

Search for code across GitHub repositories with advanced filtering.

Parameters:

• query (required): Search query (e.g., "useState in:file language:typescript")
• perPage (optional): Results per page (1-100, default: 30)
• page (optional): Page number (default: 1)

search_repositories

Find repositories matching criteria.

Parameters:

• query (required): Search query (e.g., "topic:react stars:>1000")
• perPage (optional): Results per page (1-100, default: 30)
• page (optional): Page number
• sort (optional): Sort by stars, forks, help-wanted-issues, updated
• order (optional): asc or desc

search_issues

Search issues and pull requests.

Parameters:

• query (required): Search query (e.g., "label:bug state:open")
• perPage (optional): Results per page (1-100, default: 30)
• page (optional): Page number
• sort (optional): Sort by comments, created, updated
• order (optional): asc or desc

get_repository

Get detailed information about a repository.

Parameters:

• owner (required): Repository owner
• repo (required): Repository name

get_file_content

Get raw content of a file.

Parameters:

• owner (required): Repository owner
• repo (required): Repository name
• path (required): File path
• ref (optional): Git reference (branch, tag, commit)

Development

# Build the package
bun run build

# Run in watch mode (development)
bun run dev

# Start the MCP server
bun run start

Search Query Syntax

Code Search

useState                      # Simple keyword
useState in:file             # Search in file content
language:typescript          # Language filter
repo:facebook/react          # Repository filter
org:facebook                 # Organization filter
filename:useState.ts         # Filename filter
extension:ts                 # Extension filter

Repository Search

topic:mcp                    # Topic filter
stars:>1000                  # Stars greater than
forks:true                   # Forks only
pushed:>2024-01-01           # Last push date
language:typescript          # Primary language
size:>1000                   # Repository size

Issue Search

state:open                   # State filter
label:bug                    # Label filter
author:username              # Author filter
assignee:username            # Assignee filter
comments:>5                  # Comment count
created:>2024-01-01          # Creation date

Rate Limits

GitHub API has rate limits:

• Authenticated requests: 5,000 requests/hour
• Search API: 30 requests/minute

The client automatically handles rate limiting and respects the X-RateLimit-Remaining headers.

Requirements

• Node.js 20+
• GitHub Personal Access Token
• Bun (for development)

Composability

This MCP server is designed to be composable with other MCP servers:

• Use with @mcp/registry for package discovery
• Combine with @mcp/tailscale for private GitHub Enterprise
• Integrate with @mcp/dev-node for development workflows

License

MIT

Use Case Examples

See EXAMPLES.md for a comprehensive analysis of the Polymarket & Kalshi prediction market ecosystem using this GitHub Search MCP server.