Github To MCP

🚀 GitHub to MCP

GitHub to MCP is a powerful tool that enables you to convert any GitHub repository into an MCP server within seconds. This allows AI assistants such as Claude, ChatGPT, Cursor, Windsurf, Cline, and others to instantly access any codebase, eliminating the need for manual API description or code snippet copying.

🚀 Quick Start

🌐 Web UI (Easiest)

Visit github-to-mcp.vercel.app, paste any GitHub URL, click "Generate", and then 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

• Automatically classify repository types (API, library, CLI tool, MCP server, documentation).
• Detect and parse OpenAPI/Swagger specifications.
• Extract GraphQL schemas and generate query/mutation tools.
• Parse gRPC/Protobuf service definitions.
• Support AsyncAPI specifications for event-driven APIs.
• Analyze source code to extract functions.

🌍 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

• Convert OpenAPI endpoints into callable tools with typed parameters.
• Transform GraphQL queries and mutations into tools with input validation.
• Preserve Python functions decorated with @mcp.tool.
• Turn CLI commands documented in READMEs into executable tools.
• Detect HTTP route handlers from popular frameworks.

⚡ Code Generation

• Generate complete and runnable MCP server code with all dependencies.
• Create configuration files for Claude Desktop, Cursor, and other clients.
• Provide Docker deployment templates.
• Generate 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. You can use the browser-based interface without any local installation.

💻 Usage

🌐 Web Interface

The web interface offers 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', 'graphql', 'grpc', 'mcp'],
  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');

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<'openapi' | 'readme' | 'code' | 'graphql' | 'grpc' | 'mcp'>;
  
  // 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

🏷️ 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 the following:

The classification influences which extraction strategies are prioritized and how tools are named.

🔍 Tool Extraction

Tools are extracted from multiple sources within the repository:

🏗️ 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:

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

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:

{
  "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. Select a tool from the list.
3. Fill in the required parameters.
4. Click "Execute" to run the tool.
5. View the JSON response.

The playground executes tools in a sandboxed environment and displays results in real-time.

🔗 Sharing Playground Sessions

You can share your generated tools with others:

Example:

https://github-to-mcp.vercel.app/playground?gist=abc123&name=My%20API

📁 Project Structure

github-to-mcp/
├── 📂 apps/
│   ├── 📂 web/                    # Next.js web application
│   │   ├── 📂 app/                # Next.js App Router pages
│   │   │   ├── 📂 api/            # API routes for conversion
│   │   │   ├── 📂 convert/        # Conversion page
│   │   │   ├── 📂 playground/     # Interactive playground
│   │   │   └── 📂 dashboard/      # User dashboard
│   │   ├── 📂 components/         # React components
│   │   ├── 📂 hooks/              # Custom React hooks
│   │   ├── 📂 lib/                # Utility functions
│   │   └── 📂 types/              # TypeScript type definitions
│   └── 📂 vscode/                 # VS Code extension (in development)
│
├── 📂 packages/
│   ├── 📂 core/                   # Main conversion engine
│   │   └── 📂 src/
│   │       ├── index.ts           # GithubToMcpGenerator class
│   │       ├── github-client.ts   # GitHub API client
│   │       ├── readme-extractor.ts    # README parsing
│   │       ├── code-extractor.ts      # Source code analysis
│   │       ├── graphql-extractor.ts   # GraphQL schema parsing
│   │       ├── mcp-introspector.ts    # Existing MCP server detection
│   │       ├── python-generator.ts    # Python output generation
│   │       ├── go-generator.ts        # Go output generation
│   │       └── types.ts               # Type definitions
│   │
│   ├── 📂 openapi-parser/         # OpenAPI specification parser
│   │   └── 📂 src/
│   │       ├── parser.ts          # OpenAPI parsing logic
│   │       ├── analyzer.ts        # Endpoint analysis
│   │       ├── transformer.ts     # Schema transformation
│   │       └── generator.ts       # Tool generation
│   │
│   ├── 📂 mcp-server/             # MCP server utilities
│   │   └── 📂 src/
│   │       ├── server.ts          # Base MCP server implementation
│   │       └── tools.ts           # Tool registration helpers
│   │
│   └── 📂 registry/               # Tool registry management
│       └── 📂 src/
│           └── index.ts           # Registry operations
│
├── 📂 mkdocs/                     # Documentation site (MkDocs)
│   ├── 📂 docs/                   # Markdown documentation
│   └── mkdocs.yml                 # MkDocs configuration
│
├── 📂 tests/                      # Integration tests
│   ├── 📂 fixtures/               # Test fixture repositories
│   │   ├── 📂 express-app/        # Express.js test app
│   │   ├── 📂 fastapi-app/        # FastAPI test app
│   │   ├── 📂 graphql/            # GraphQL test schemas
│   │   └── 📂 openapi/            # OpenAPI test specs
│   └── 📂 integration/            # Integration test files
│
├── 📂 templates/                  # Code generation templates
│   ├── Dockerfile.python.template
│   └── Dockerfile.typescript.template
│
├── package.json                   # Root package configuration
├── pnpm-workspace.yaml            # pnpm workspace configuration
├── tsconfig.json                  # TypeScript configuration
└── vitest.config.ts               # Test configuration

🔨 Development

Prerequisites

Local Setup

# Clone the repository
git clone https://github.com/nirholas/github-to-mcp.git
cd github-to-mcp

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Start the development server
pnpm dev

The web application will be available at http://localhost:3000.

Building

# Build all packages
pnpm build

# Build specific package
pnpm --filter @nirholas/github-to-mcp build
pnpm --filter @github-to-mcp/openapi-parser build
pnpm --filter web build

Testing

# Run all tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Run tests with coverage
pnpm test:coverage

# Run specific test file
pnpm test -- tests/integration/openapi-conversion.test.ts

Code Quality

# Run linting
pnpm lint

# Type checking
pnpm typecheck

🏗️ Architecture Overview

The system follows a pipeline architecture:

Input (GitHub URL)
       │
       ▼
┌──────────────────┐
│  GitHub Client   │  Fetches repository metadata, files, and README
└──────────────────┘
       │
       ▼
┌──────────────────┐
│   Classifier     │  Determines repository type and structure
└──────────────────┘
       │
       ▼
┌──────────────────┐
│   Extractors     │  Multiple extractors run in parallel:
│  ├─ OpenAPI      │  • Parse API specifications
│  ├─ GraphQL      │  • Parse GraphQL schemas
│  ├─ README       │  • Extract examples from documentation
│  ├─ Code         │  • Analyze source code
│  └─ MCP          │  • Detect existing MCP tools
└──────────────────┘
       │
       ▼
┌──────────────────┐
│  Deduplicator    │  Removes duplicate tools, merges similar ones
└──────────────────┘
       │
       ▼
┌──────────────────┐
│   Validator      │  Validates tool schemas, adds confidence scores
└──────────────────┘
       │
       ▼
┌──────────────────┐
│   Generator      │  Produces output code in target language
└──────────────────┘
       │
       ▼
Output (MCP Server Code + Configuration)

Each extractor produces a list of ExtractedTool objects with a standardized schema. The deduplicator and validator ensure consistency before the generator produces the final output.

📥 Supported Input Formats

API Specifications

Source Code Languages

📤 Output Formats

TypeScript Server

The default output is a TypeScript MCP server using the official @modelcontextprotocol/sdk package:

import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const server = new Server({
  name: 'generated-server',
  version: '1.0.0',
}, {
  capabilities: {
    tools: {},
  },
});

server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [/* generated tools */],
}));

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  // Tool dispatch logic
});

const transport = new StdioServerTransport();
await server.connect(transport);

Python Server

Python output uses the MCP Python SDK:

from mcp.server import Server
from mcp.server.stdio import stdio_server

server = Server("generated-server")

@server.tool()
async def example_tool(param: str) -> str:
    """Tool description."""
    # Implementation
    
async def main():
    async with stdio_server() as (read_stream, write_stream):
        await server.run(read_stream, write_stream)

if __name__ == "__main__":
    import asyncio
    asyncio.run(main())

Configuration Files

Each generated server includes:

⚠️ Limitations

🔧 Troubleshooting

export GITHUB_TOKEN=ghp_xxxxxxxxxxxx

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for detailed guidelines on:

• Setting up the development environment
• Code style and formatting requirements
• Testing requirements
• Pull request process

🐛 Reporting Issues

When reporting issues, please include:

• Repository URL that caused the issue (if public)
• Error messages or unexpected behavior
• Node.js and pnpm versions
• Operating system

📄 License

Apache 2.0. See LICENSE for details.

🔗 Links

🌐 Live HTTP Deployment

GitHub to MCP is deployed and accessible over HTTP via MCP Streamable HTTP transport — no local installation required.

Endpoint:

https://modelcontextprotocol.name/mcp/github-to-mcp

Connect from any MCP Client

Add to your MCP client configuration (Claude Desktop, Cursor, SperaxOS, etc.):

{
  "mcpServers": {
    "github-to-mcp": {
      "type": "http",
      "url": "https://modelcontextprotocol.name/mcp/github-to-mcp"
    }
  }
}

Available Tools (2)

Example Requests

Get repository info:

curl -X POST https://modelcontextprotocol.name/mcp/github-to-mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_repo_info","arguments":{"owner":"nirholas","repo":"universal-crypto-mcp"}}}'

Search repositories:

curl -X POST https://modelcontextprotocol.name/mcp/github-to-mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_repos","arguments":{"query":"mcp server crypto"}}}'

List All Tools

curl -X POST https://modelcontextprotocol.name/mcp/github-to-mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Also Available On

• SperaxOS — Browse and install from the MCP marketplace
• All 27 MCP servers — See the full catalog at modelcontextprotocol.name

Powered by modelcontextprotocol.name — the open MCP HTTP gateway