# Github To MCP Guide

> Guide to converting GitHub repositories into MCP servers automatically. Extract tools from OpenAPI, GraphQL, and REST APIs for Claude Desktop, Cursor, Windsurf, Cline, and VS Code. AI-powered code generation creates type-safe TypeScript/Python MCP servers. Zero config — just paste a repo URL.

- Skill: `nirholas/github-to-mcp-guide` (Agent Skill)
- Install (CLI): `npx skillmds@latest add nirholas/github-to-mcp-guide`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nirholas/github-to-mcp-guide/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: nirholas (https://skillmd.com/u/nirholas)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/nirholas/github-to-mcp-guide

---


# GitHub-to-MCP Conversion Guide

Convert any GitHub repository into an MCP server automatically. The tool analyzes the repo's API surface (OpenAPI specs, GraphQL schemas, REST endpoints) and generates a working MCP server with type-safe tools.

## How It Works

```
GitHub Repo URL
    │
    ▼
1. Clone & analyze repo
    │
    ▼
2. Detect API surface
   ├── OpenAPI/Swagger specs
   ├── GraphQL schemas
   ├── REST route definitions
   └── Function exports
    │
    ▼
3. Generate MCP server
   ├── TypeScript or Python
   ├── Type-safe tool definitions
   ├── Parameter validation
   └── Error handling
    │
    ▼
4. Ready-to-use MCP server
```

## Quick Start

```bash
npx github-to-mcp https://github.com/owner/repo
```

This generates a ready-to-use MCP server in `./mcp-output/`.

## Supported API Formats

| Format | Detection | Example |
|--------|-----------|---------|
| **OpenAPI 3.x** | `openapi.json`, `swagger.yaml` | REST APIs with full schema |
| **GraphQL** | `schema.graphql`, introspection | Query/mutation → tools |
| **Express/Fastify** | Route scanning | `app.get('/api/...')` → tools |
| **Next.js API** | Route file detection | `app/api/*/route.ts` → tools |
| **Function exports** | Named export analysis | `export function doThing()` → tools |

## Output Options

### TypeScript MCP Server
```bash
github-to-mcp https://github.com/owner/repo --lang typescript
```
Generates a Node.js MCP server with full TypeScript types.

### Python MCP Server
```bash
github-to-mcp https://github.com/owner/repo --lang python
```
Generates a Python MCP server using the official MCP SDK.

## AI-Powered Generation

When the API surface is ambiguous, the tool uses AI (GPT-4 or Claude) to:
- Infer parameter types from usage patterns
- Generate meaningful tool descriptions
- Create example inputs for each tool
- Handle edge cases in API design

## Use Cases

### Turn a DeFi Protocol into MCP Tools
```bash
github-to-mcp https://github.com/aave/aave-v3-core
# → Generates MCP tools for supply, borrow, repay, liquidate, etc.
```

### Convert a Data API
```bash
github-to-mcp https://github.com/nirholas/crypto-data-aggregator
# → Generates MCP tools for price queries, portfolio tracking, alerts
```

### Make Internal Tools AI-Accessible
```bash
github-to-mcp https://github.com/your-company/internal-api
# → Your internal API is now accessible to AI agents
```

## Integration with SperaxOS

github-to-mcp is particularly useful for the SperaxOS ecosystem:
- Convert DeFi protocol repos into MCP tools
- Auto-generate tool manifests for the skill marketplace
- Create agent tools from any Sperax ecosystem repo

## Links

- GitHub: https://github.com/nirholas/github-to-mcp
- MCP Specification: https://modelcontextprotocol.io
- SperaxOS: https://github.com/nirholas/sperax