Github To Mcp

GitHub to MCP

Convert any GitHub repository into an MCP server in seconds

Give Claude, ChatGPT, Cursor, Windsurf, Cline, and any AI assistant instant access to any codebase.

🌐 Web App • 🚀 Quick Start • ✨ Features • 📖 Docs

---

📋 Table of Contents

• [Introduction](#-introduction)
• [What is MCP](#-what-is-mcp)
• [Quick Start](#-quick-start)
• [Features](#-features)
• [Installation](#-installation)
• [Usage](#-usage)
• [How It Works](#-how-it-works)
• [Generated Tools](#-generated-tools)
• [Configuration](#%EF%B8%8F-configuration)
• [Integrating with AI Assistants](#-integrating-with-ai-assistants)
• [Interactive Playground](#-interactive-playground)
• [Project Structure](#-project-structure)
• [Development](#-development)
• [Architecture Overview](#-architecture-overview)
• [Supported Input Formats](#-supported-input-formats)
• [Output Formats](#-output-formats)
• [Limitations](#%EF%B8%8F-limitations)
• [Troubleshooting](#-troubleshooting)
• [Contributing](#-contributing)
• [License](#-license)

---

📖 Introduction

GitHub to MCP bridges the gap between code repositories and AI assistants. Instead of manually describing APIs or copying code snippets into chat windows, this tool generates a standardized interface that allows AI systems to programmatically explore, read, and interact with any GitHub repository.

The generated MCP servers provide tools that AI assistants can invoke to read files, search code, list directory structures, and call API endpoints discovered within the repository. This enables AI assistants to have deep, structured access to codebases without requiring manual context management.

┌─────────────────────────────────────────────────────────────┐
│                     GitHub Repository                       │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│  1. Fetch & Classify  →  Detect repo type (API/CLI/Lib)     │
│  2. Extract Tools     →  OpenAPI, GraphQL, Code, README     │
│  3. Generate Server   →  TypeScript or Python MCP server    │
│  4. Bundle Output     →  Complete package with dependencies │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│              Ready-to-use MCP Server + Config               │
└─────────────────────────────────────────────────────────────┘

---

🔌 What is MCP

The Model Context Protocol (MCP) is an open standard developed by Anthropic that defines how AI assistants communicate with external tools and data sources. MCP servers expose "tools" that AI models can invoke, along with "resources" that provide context and "prompts" that guide interactions.

When you connect an MCP server to an AI assistant like Claude Desktop, the assistant gains the ability to call the tools defined by that server. For example, a GitHub MCP server might expose tools like read_file, search_code, or list_pull_requests, which the AI can invoke to gather information needed to answer questions or complete tasks.

This project generates MCP servers from GitHub repositories, automatically creating tools based on the repository's contents, APIs, and documentation.

---

🚀 Quick Start

🌐 Web UI (Easiest)

Visit github-to-mcp.vercel.app — Paste any GitHub URL, click Generate, download your MCP server.

💻 CLI (One Command)

npx @nirholas/github-to-mcp https://github.com/stripe/stripe-node

📦 Programmatic (For Automation)

import { generateFromGithub } from '@nirholas/github-to-mcp';

const result = await generateFromGithub('https://github.com/stripe/stripe-node');
console.log(`Generated ${result.tools.length} tools`);
await result.save('./my-mcp-server');

---

✨ Features

🔬 Repository Analysis

• Automatic repository type classification (API, library, CLI tool, MCP server, documentation)
• Detection and parsing of OpenAPI/Swagger specifications
• GraphQL schema extraction and query/mutation tool generation
• gRPC/Protobuf service definition parsing
• AsyncAPI specification support for event-driven APIs
• Source code analysis for function extraction

🌍 Multi-Language Support

Input repositories:

• TypeScript and JavaScript
• Python
• Go
• Java and Kotlin
• Rust
• Ruby
• C# and F#

Output MCP servers:

• TypeScript (using the official MCP SDK)
• Python (using the MCP Python SDK)
• Go (using community MCP libraries)

🔧 Tool Extraction

• OpenAPI endpoints become callable tools with typed parameters
• GraphQL queries and mutations become tools with input validation
• Python functions decorated with @mcp.tool are preserved
• CLI commands documented in READMEs become executable tools
• HTTP route handlers from popular frameworks are detected

⚡ Code Generation

• Complete, runnable MCP server code with all dependencies
• Configuration files for Claude Desktop, Cursor, and other clients
• Docker deployment templates
• TypeScript type definitions for all generated tools

---

📥 Installation

From Source

Clone the repository and install dependencies:

git clone https://github.com/nirholas/github-to-mcp.git
cd github-to-mcp
pnpm install
pnpm build

Using the Web Interface

The web application is deployed at github-to-mcp.vercel.app. Use the browser-based interface without any local installation.

---

📖 Usage

🌐 Web Interface

The web interface provides the simplest way to convert repositories:

1. Navigate to the web application
2. Enter a GitHub repository URL (e.g., https://github.com/owner/repo)
3. Optionally configure extraction options
4. Click "Generate" to analyze the repository
5. Review the generated tools and code
6. Download the MCP server package or copy the configuration

The web interface also provides an interactive playground where you can test generated tools before downloading.

💻 Command Line Interface

After building the project locally, you can use the CLI:

# Basic usage
node packages/core/dist/cli.mjs https://github.com/owner/repo

# Specify output directory
node packages/core/dist/cli.mjs https://github.com/owner/repo --output ./my-mcp-server

# Generate Python instead of TypeScript
node packages/core/dist/cli.mjs https://github.com/owner/repo --language python

# Include only specific extraction sources
node packages/core/dist/cli.mjs https://github.com/owner/repo --sources openapi,readme

# Use a GitHub token for private repos or higher rate limits
GITHUB_TOKEN=ghp_xxx node packages/core/dist/cli.mjs https://github.com/owner/repo

📦 Programmatic API

Import the generator in your own TypeScript or JavaScript code:

import { GithubToMcpGenerator } from '@nirholas/github-to-mcp';

const generator = new GithubToMcpGenerator({
  githubToken: process.env.GITHUB_TOKEN,
  sources: ['openapi', 'readme', 'code'],
  outputLanguage: 'typescript'
});

const result = await generator.generate('https://github.com/owner/repo');

console.log(`Repository: ${result.name}`);
console.log(`Classification: ${result.classification.type}`);
console.log(`Generated ${result.tools.length} tools`);

// Access the generated code
console.log(result.code);

// Save to disk
await result.save('./output-directory');

📋 Generator Options Interface

interface GithubToMcpOptions {
  // GitHub personal access token for API authentication
  githubToken?: string;
  
  // Which sources to extract tools from
  // Default: ['openapi', 'readme', 'code', 'graphql', 'mcp']
  sources?: Array;
  
  // Output language for generated server
  // Default: 'typescript'
  outputLanguage?: 'typescript' | 'python' | 'go';
  
  // Include universal tools (read_file, list_files, etc.)
  // Default: true
  includeUniversalTools?: boolean;
  
  // Maximum number of tools to generate
  // Default: 100
  maxTools?: number;
  
  // Specific branch to analyze
  // Default: repository's default branch
  branch?: string;
}

---

⚙️ How It Works

The conversion process follows these stages:

🏷️ Repository Classification

The generator first analyzes the repository to determine its type and structure:

1. Fetch repository metadata from the GitHub API
2. Download and parse the README file
3. Examine package.json, setup.py, go.mod, or other manifest files
4. Scan for API specification files (openapi.json, schema.graphql, etc.)
5. Classify the repository as one of:

| Classification | Description | |----------------|-------------| | mcp-server | An existing MCP server implementation | | api-sdk | A client library for an API | | cli-tool | A command-line application | | library | A general-purpose code library | | documentation | Primarily documentation content | | data | Data files or datasets | | unknown | Unclassified repository |

Classification influences which extraction strategies are prioritized and how tools are named.

🔍 Tool Extraction

Tools are extracted from multiple sources within the repository:

📄 OpenAPI/Swagger Extraction

When an OpenAPI specification is found:

1. Parse the specification (JSON or YAML, v2 or v3)
2. Extract each endpoint as a potential tool
3. Convert path parameters, query parameters, and request bodies to tool input schemas
4. Generate descriptions from operation summaries and descriptions
5. Map HTTP methods to appropriate tool semantics

🔷 GraphQL Extraction

When GraphQL schemas are found:

1. Parse .graphql or .gql schema files
2. Extract Query type fields as read-only tools
3. Extract Mutation type fields as write tools
4. Convert GraphQL input types to JSON Schema for tool inputs
5. Handle nested types and custom scalars

📖 README Extraction

The README is analyzed for:

1. Code blocks showing CLI usage patterns
2. API endpoint examples with curl or fetch
3. Function call examples with parameters
4. Installation and usage instructions

Extracted examples become tools with inferred parameter schemas.

💻 Source Code Extraction

For supported languages, the source code is analyzed:

1. Python: Functions decorated with @mcp.tool, @server.tool, or similar
2. TypeScript: Exported functions with JSDoc annotations
3. Go: HTTP handlers from Gin, Echo, Chi, Fiber, or Gorilla Mux
4. Java/Kotlin: Methods annotated with @GetMapping, @PostMapping, etc.
5. Rust: Route handlers from Actix-web, Axum, or Rocket

🔌 MCP Server Introspection

If the repository is already an MCP server:

1. Detect server.tool() definitions
2. Extract tool names, descriptions, and schemas
3. Preserve existing tool implementations where possible

🏗️ Code Generation

After tools are extracted, the generator produces:

1. A main server file implementing the MCP protocol
2. Tool handler functions for each extracted tool
3. Type definitions for all input and output schemas
4. A package.json or equivalent with required dependencies
5. Configuration files for popular MCP clients
6. Optional Docker deployment files

The generated code is complete and runnable without modification.

---

🛠️ Generated Tools

🌐 Universal Tools

Every generated MCP server includes these baseline tools for repository exploration:

| Tool | Description | Parameters | |------|-------------|------------| | get_readme | Retrieve the repository's README content | None | | list_files | List files and directories at a given path | path (optional, defaults to root) | | read_file | Read the contents of a specific file | path (required) | | search_code | Search for patterns across the repository | query (required), path (optional) |

These tools ensure that even if no APIs or functions are detected, the AI assistant can still explore and understand the repository.

🔧 Extracted Tools

Additional tools are generated based on repository contents:

From OpenAPI Specifications

Each API endpoint becomes a tool:

POST /users      →  create_user(name: string, email: string)
GET /users/{id}  →  get_user(id: string)
PUT /users/{id}  →  update_user(id: string, name?: string, email?: string)
DELETE /users/{id} →  delete_user(id: string)
GET /users       →  list_users(page?: number, limit?: number)

From GraphQL Schemas

Queries and mutations become tools:

type Query {
  user(id: ID!): User         →  get_user(id: string)
  users(first: Int): [User]   →  list_users(first?: number)
}

type Mutation {
  createUser(input: CreateUserInput!): User  →  create_user(input: object)
}

From Python Code

@server.tool()
async def analyze_sentiment(text: str) -> str:
    """Analyze the sentiment of the given text."""
    # Implementation

Becomes: analyze_sentiment(text: string) → "Analyze the sentiment of the given text."

From README Examples

CLI commands documented in READMEs:

# Create a new project
mycli create --name myproject --template typescript

Becomes: mycli_create(name: string, template?: string)

---

⚙️ Configuration

🔐 Environment Variables

| Variable | Description | Required | |----------|-------------|----------| | GITHUB_TOKEN | GitHub personal access token for API access | No (but recommended) | | GITHUB_API_URL | Custom GitHub API URL for Enterprise | No |

GitHub Token

Without a token, GitHub API requests are limited to 60 per hour. With a token, the limit increases to 5,000 per hour. For private repositories, a token with appropriate access is required.

Create a token at: https://github.com/settings/tokens

Required scopes:

• repo (for private repositories)
• public_repo (for public repositories only)

🎛️ Generator Options

When using the programmatic API, you can configure:

const generator = new GithubToMcpGenerator({
  // Authentication
  githubToken: process.env.GITHUB_TOKEN,
  
  // Extraction sources to enable
  sources: ['openapi', 'readme', 'code', 'graphql', 'grpc', 'mcp'],
  
  // Output configuration
  outputLanguage: 'typescript', // or 'python', 'go'
  
  // Tool filtering
  includeUniversalTools: true,
  maxTools: 100,
  
  // Repository options
  branch: 'main', // specific branch to analyze
});

---

🤖 Integrating with AI Assistants

Claude Desktop

Add the generated server to your Claude Desktop configuration:

| Platform | Config Path | |----------|-------------| | macOS | ~/Library/Application Support/Claude/claude_desktop_config.json | | Windows | %APPDATA%\Claude\claude_desktop_config.json |

{
  "mcpServers": {
    "my-repo": {
      "command": "node",
      "args": ["/absolute/path/to/generated/server.mjs"],
      "env": {
        "GITHUB_TOKEN": "ghp_xxxx"
      }
    }
  }
}

> ⚠️ Restart Claude Desktop after modifying the configuration.

Cursor

Cursor supports MCP servers through its settings. Add the server path in Cursor's MCP configuration panel, or edit the configuration file directly:

{
  "mcp": {
    "servers": {
      "my-repo": {
        "command": "node",
        "args": ["/path/to/server.mjs"]
      }
    }
  }
}

💻 VS Code with Continue

If using the Continue extension for VS Code:

{
  "models": [...],
  "mcpServers": {
    "my-repo": {
      "command": "node",
      "args": ["/path/to/server.mjs"]
    }
  }
}

🔌 Other MCP Clients

Any MCP-compatible client can use the generated servers. The server communicates over stdio by default, accepting JSON-RPC messages on stdin and responding on stdout.

To run manually:

node server.mjs

The server will wait for MCP protocol messages on stdin.

---

🎮 Interactive Playground

The web application includes an interactive playground for testing generated tools:

1. After generating tools from a repository, click "Open in Playground"
2. Se

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: nirholas
• Source: nirholas/github-to-mcp
• License: Apache-2.0
• Homepage: https://github-to-mcp.vercel.app

Install and usage instructions live in the source repository linked above.