🔒 mcp-server-hub

A safe-by-default, beginner-friendly hub for MCP (Model Context Protocol) servers that connect AI coding assistants to real-world developer tools.

Give your AI IDE — Claude Desktop, Cursor, Windsurf, or any MCP client — read-only access to GitHub repositories, issues, pull requests, and source files. No write operations. No risk.

Key Features

• 🛡️ Read-only by design — every tool is strictly read-only. No creates, no deletes, no mutations.
• 🔑 Secret-safe — tokens are never logged, never leaked in errors, and automatically redacted.
• ✅ Input validation — all inputs validated with Zod before any API call.
• 🧩 Plug and play — one command to build, one config block to connect.
• 📖 Beginner-friendly — clean code, clear docs, and a simple project structure.

Table of Contents

• Available Servers
• Tech Stack
• Prerequisites
• Getting Started
• Connect to Your AI IDE
• Tool Reference
• Architecture
• Environment Variables
• Available Scripts
• Security
• Troubleshooting
• Roadmap
• Contributing
• License

Available Servers

| Server | Description | Status | |--------|-------------|--------| | github-helper | Read-only access to GitHub repos, issues, PRs, and files | ✅ v0.1.0 | | supabase-helper | Supabase database and auth inspection | 🗓️ Planned | | vercel-helper | Vercel deployment and project info | 🗓️ Planned | | cloudflare-helper | Cloudflare Workers and DNS info | 🗓️ Planned |

Only github-helper is implemented. Future servers are planned but not yet built.

Tech Stack

• Language: TypeScript (strict mode)
• Runtime: Node.js 18+
• Package Manager: pnpm (workspace monorepo)
• Validation: Zod
• Environment: dotenv
• MCP SDK: @modelcontextprotocol/sdk
• Transport: Stdio (local subprocess — no network server needed)

Prerequisites

Before starting, make sure you have:

• Node.js v18 or later
• pnpm v8 or later — install with npm install -g pnpm
• A GitHub Personal Access Token (classic or fine-grained)

Getting Started

1. Clone the Repository

git clone https://github.com/kwaqtech/mcp-server-hub.git
cd mcp-server-hub

2. Install Dependencies

pnpm install

This installs all dependencies across the monorepo (shared utilities + github-helper server).

3. Build

pnpm build

This compiles TypeScript to JavaScript for all packages. The compiled output goes to dist/ in each package.

4. Configure Your GitHub Token

cp servers/github-helper/.env.example servers/github-helper/.env

Edit servers/github-helper/.env and replace the placeholder:

GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

💡 Tip: Use a fine-grained token with read-only access to public repos. This is the safest option.

5. Test It Locally

Run the server directly to verify it starts:

node servers/github-helper/dist/index.js

You should see [INFO] github-helper MCP server starting... on stderr. Press Ctrl+C to stop. If you see an error about GITHUB_TOKEN, double-check your .env file.

Connect to Your AI IDE

Claude Desktop

1. Open your Claude Desktop config file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Add the github-helper server:

{
  "mcpServers": {
    "github-helper": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server-hub/servers/github-helper/dist/index.js"],
      "env": {
        "GITHUB_TOKEN": "your_token_here"
      }
    }
  }
}

3. Replace /absolute/path/to/mcp-server-hub with the actual path on your system.
4. Replace your_token_here with your GitHub Personal Access Token.
5. Restart Claude Desktop.

Cursor

1. Open Cursor Settings → MCP Servers, or edit .cursor/mcp.json in your project:

{
  "mcpServers": {
    "github-helper": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server-hub/servers/github-helper/dist/index.js"],
      "env": {
        "GITHUB_TOKEN": "your_token_here"
      }
    }
  }
}

2. Restart Cursor or reload the MCP configuration.

Verify the Connection

Once connected, try asking your AI assistant:

• "What is the description of the facebook/react repo?"
• "Show me the open issues on nodejs/node"
• "Get the README from modelcontextprotocol/typescript-sdk"
• "List the pull requests on vercel/next.js"
• "Show me the contents of package.json in expressjs/express"

Tool Reference

github_get_repo_info

Get metadata about a GitHub repository.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | owner | string | ✅ | Repository owner (user or organization) | | repo | string | ✅ | Repository name |

Returns: Repository name, URL, description, language, stars, forks, open issues, watchers, default branch, creation date, license, topics, and archive/private status.

github_get_readme

Fetch the raw README content of a repository.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | owner | string | ✅ | Repository owner | | repo | string | ✅ | Repository name |

Returns: The full README text (markdown).

github_list_issues

List issues in a repository with optional filters. Automatically excludes pull requests.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | owner | string | ✅ | — | Repository owner | | repo | string | ✅ | — | Repository name | | state | "open" | "closed" | "all" | — | "open" | Filter by issue state | | labels | string | — | — | Comma-separated label names | | per_page | number (1–100) | — | 10 | Results per page | | page | number | — | 1 | Page number |

Returns: Issue number, title, state, author, labels, comment count, creation date, and URL for each issue.

github_list_pull_requests

List pull requests in a repository with optional state filter.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | owner | string | ✅ | — | Repository owner | | repo | string | ✅ | — | Repository name | | state | "open" | "closed" | "all" | — | "open" | Filter by PR state | | per_page | number (1–100) | — | 10 | Results per page | | page | number | — | 1 | Page number |

Returns: PR number, title, state, draft status, author, branch info, creation/merge date, and URL.

github_get_file_content

Read the content of a file from a repository.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | owner | string | ✅ | — | Repository owner | | repo | string | ✅ | — | Repository name | | path | string | ✅ | — | File path (e.g., src/index.ts) | | ref | string | — | default branch | Branch, tag, or commit SHA |

Returns: The raw file content as text.

Architecture

Project Structure

mcp-server-hub/
├── AGENTS.md                        # AI agent rules (source of truth)
├── README.md                        # This file
├── SECURITY.md                      # Security policy & vulnerability reporting
├── CONTRIBUTING.md                  # Contribution guidelines
├── LICENSE                          # MIT License
├── package.json                     # Root monorepo scripts
├── pnpm-workspace.yaml              # Defines packages/* and servers/* workspaces
├── tsconfig.base.json               # Shared strict TypeScript configuration
├── .gitignore                       # Ignores node_modules, dist, .env
├── .env.example                     # Root env template
│
├── docs/                            # Documentation
│   ├── getting-started.md
│   ├── claude-desktop.md
│   ├── cursor.md
│   ├── security-guide.md
│   └── troubleshooting.md
│
├── packages/
│   └── shared/                      # @mcp-server-hub/shared
│       ├── package.json
│       ├── tsconfig.json
│       └── src/
│           ├── index.ts             # Barrel export
│           ├── env.ts               # Safe env loading + Zod validation
│           ├── logger.ts            # stderr logger with secret redaction
│           ├── errors.ts            # Typed error classes (safe messages)
│           └── responses.ts         # MCP response builders
│
└── servers/
    └── github-helper/               # @mcp-server-hub/github-helper
        ├── package.json
        ├── tsconfig.json
        ├── README.md
        ├── .env.example
        └── src/
            ├── index.ts             # Entry point — McpServer + stdio transport
            ├── config.ts            # Zod-validated GITHUB_TOKEN config
            ├── github-client.ts     # Read-only GitHub REST API client
            └── tools/
                ├── get-repo-info.ts
                ├── get-readme.ts
                ├── list-issues.ts
                ├── list-pull-requests.ts
                └── get-file-content.ts

How It Works

┌──────────────┐     stdio      ┌──────────────────┐    HTTPS     ┌──────────────┐
│  AI IDE      │ ◄────────────► │  github-helper    │ ──────────►  │  GitHub API  │
│  (Claude,    │   MCP JSON     │  MCP Server       │   GET only   │  api.github  │
│   Cursor)    │                │                    │              │  .com        │
└──────────────┘                └──────────────────┘              └──────────────┘

1. Your AI IDE launches the server as a subprocess.
2. Communication happens over stdio using the MCP JSON protocol.
3. When the AI calls a tool, the server validates input with Zod.
4. The server makes a read-only GET request to the GitHub REST API.
5. The response is formatted as structured text and returned to the AI.
6. All logging goes to stderr (never to stdout, which is reserved for MCP).

Key Design Decisions

| Decision | Rationale | |----------|-----------| | McpServer (high-level API) | Official recommended class from @modelcontextprotocol/sdk. Handles capability negotiation automatically. | | Stdio transport | Standard for local MCP servers. No HTTP server to configure or expose. | | All logging to stderr | MCP uses stdout for protocol messages. Any stdout pollution breaks the protocol. | | Automatic secret redaction | The logger detects and redacts GitHub PAT patterns (ghp_*, github_pat_*, etc.) in any log message. | | Safe error classes | Error messages never contain raw upstream details. toSafeError() wraps unknown errors into generic messages. | | Zod for everything | Config validation and tool input schemas both use Zod for consistent, declarative validation. |

Shared Package (@mcp-server-hub/shared)

Reusable utilities shared across all servers:

| Module | Purpose | |--------|---------| | env.ts | loadEnv(), requireEnv(), validateEnv() — safe env loading that never exposes values in errors | | logger.ts | logInfo(), logWarn(), logError(), logDebug() — logs to stderr with automatic token redaction | | errors.ts | NotFoundError, AuthError, RateLimitError, UpstreamError, toSafeError() — typed, safe errors | | responses.ts | textResponse(), errorResponse() — consistent MCP tool response format |

Environment Variables

Required

| Variable | Description | How to Get | |----------|-------------|------------| | GITHUB_TOKEN | GitHub Personal Access Token | github.com/settings/tokens |

Token Permissions Guide

| Use Case | Recommended Token Scope | |----------|------------------------| | Public repos only | No scopes needed (or public_repo for classic tokens) | | Private repos | repo scope (classic) or fine-grained with read-only repo access |

Important Rules

• ❌ Never commit .env files (already in .gitignore)
• ❌ Never hardcode tokens in source code
• ✅ Use .env.example as a template — it only contains placeholders
• ✅ When configuring in AI IDEs, pass tokens via the env config field

Available Scripts

Run these from the repository root:

| Command | Description | |---------|-------------| | pnpm install | Install all dependencies across the monorepo | | pnpm build | Compile TypeScript for all packages and servers | | pnpm typecheck | Type-check all packages without emitting files | | pnpm lint | Run linting across all packages (not yet configured) | | pnpm test | Run tests (not yet configured) |

Run these from servers/github-helper/:

| Command | Description | |---------|-------------| | pnpm start | Start the compiled github-helper server | | pnpm build | Compile this server only | | pnpm typecheck | Type-check this server only |

Security

Security Model

All v0.x servers follow these rules:

• ✅ Every tool is read-only — no tool can create, modify, or delete anything
• ✅ All inputs are validated with Zod before any API call
• ✅ Tokens are loaded from environment variables, never hardcoded
• ✅ Error messages are sanitized — they never contain tokens, headers, or stack traces
• ✅ The logger automatically redacts known secret patterns (GitHub PATs, Bearer tokens)
• ✅ All API calls use HTTPS
• ✅ No data is stored, cached, or forwarded beyond the MCP response

Forbidden Operations

These tool patterns are strictly forbidden in v0.x:

delete_*    update_*    create_*    merge_*    execute_*
run_shell   run_command push_commit write_file edit_file

Reporting Vulnerabilities

See SECURITY.md for responsible disclosure instructions.

Troubleshooting

"GITHUB_TOKEN is required"

Your .env file is missing or empty. Copy the template and add your token:

cp servers/github-helper/.env.example servers/github-helper/.env
# Edit .env and add your token

"Cannot find module" when starting

The project hasn't been built. Run:

pnpm build

Server not appearing in Claude Desktop

• Make sure you restarted Claude Desktop after editing the config.
• Verify the path to dist/index.js is absolute, not relative.
• Confirm node is in your system PATH.

401 Unauthorized / 403 Forbidden

• Your token may be expired — regenerate at github.com/settings/tokens.
• You may have hit the API rate limit (5,000 requests/hour). Wait and retry.
• Private repos require a token with repo scope.

404 Not Found

• Check for typos in the owner/repo name.
• The file path doesn't exist in that repository.
• Private repos require proper token permissions.

For more, see docs/troubleshooting.md.

Roadmap

• [x] github-helper — read-only GitHub MCP server
• [ ] Add ESLint for consistent code style
• [ ] Add unit tests for tools and shared utilities
• [ ] supabase-helper — read-only Supabase inspection
• [ ] vercel-helper — read-only Vercel deployment info
• [ ] cloudflare-helper — read-only Cloudflare Workers/DNS info

Contributing

See CONTRIBUTING.md for development setup and guidelines.

Quick version:

git clone https://github.com/kwaqtech/mcp-server-hub.git
cd mcp-server-hub
pnpm install
pnpm build

All contributions must follow the read-only security model. Do not submit write-capable tools.

License

MIT — see LICENSE.