lightweight-github-mcp

A lightweight proxy server that wraps @modelcontextprotocol/server-github and exposes only whitelisted tools via YAML configuration. This dramatically reduces context consumption (100+ tools → 10-20 tools).

Installation

# Install dependencies
npm install

# Build
npm run build

Usage

# Run the server
npm start

# Development mode (watch)
npm run dev

# Test with MCP Inspector
npx @modelcontextprotocol/inspector node dist/index.js

Architecture

Claude Desktop/Code
        │ MCP Protocol (stdio)
        ▼
┌─────────────────────────────┐
│  lightweight-github-mcp     │
│  ┌─────────┐  ┌──────────┐  │
│  │MCP      │→ │Tool      │→ │ config.yaml (allowedTools)
│  │Server   │  │Filter    │  │
│  └─────────┘  └──────────┘  │
│         ↑          │        │
│         │    ┌─────▼─────┐  │
│         │    │MCP Client │  │
│         │    └─────┬─────┘  │
└─────────┼──────────┼────────┘
          │          │ spawn child process
          │          ▼
          │  @modelcontextprotocol/server-github (~100 tools)
          │
    Claude requests

Key Components

• src/index.ts - Entry point, config loading, server initialization
• src/server.ts - MCP server implementation, tool filtering, meta-tool handlers
• src/upstream-client.ts - Child process management for upstream GitHub MCP
• src/config.ts - YAML configuration loading and validation
• config.yaml - Tool whitelist configuration

Meta-Tools (Always Available)

The proxy provides four built-in meta-tools that are always exposed:

• list_all_upstream_tools - List all upstream tools (allowed + blocked)
• list_blocked_tools - List blocked tools by category
• search_upstream_tools - Search upstream tools by keyword
• get_tool_info - Get details about a specific tool

These help Claude discover tools and guide users to add needed tools to the whitelist.

Configuration

config.yaml

allowedTools:
  - get_file_contents
  - create_issue
  # ... only listed tools are exposed

upstream:
  command: npx
  args:
    - "-y"
    - "@modelcontextprotocol/server-github"

Config File Lookup Order

1. CONFIG_PATH environment variable
2. ./config.yaml (current directory)
3. Project root config.yaml

Environment Variables

Variable	Required	Description
GITHUB_PERSONAL_ACCESS_TOKEN	Yes	GitHub Personal Access Token
CONFIG_PATH	No	Path to config.yaml

Claude Desktop Configuration

Add the following to your Claude Desktop configuration file:

{
  "mcpServers": {
    "github-lite": {
      "command": "node",
      "args": ["/path/to/lightweight-github-mcp/dist/index.js"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx"
      }
    }
  }
}

License

MIT