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

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

github-to-mcp https://github.com/owner/repo --lang typescript

Generates a Node.js MCP server with full TypeScript types.

Python MCP Server

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

github-to-mcp https://github.com/aave/aave-v3-core
# → Generates MCP tools for supply, borrow, repay, liquidate, etc.

Convert a Data API

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

Make Internal Tools AI-Accessible

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