GitHub v3 REST API MCP Server

This MCP (Model Content Protocol) server provides access to GitHub v3 REST API API functionality through STDIO transport mode with FastMCP.

Features

• FastMCP-based server with decorator pattern
• Automatic tool registration via @mcp.tool() decorators
• Type-safe parameter handling
• Comprehensive error handling and logging
• Easy configuration through environment variables

Prerequisites

• Python 3.10 or later
• pip package manager

Installation

1. Install dependencies:

pip install -r requirements.txt

2. Configure environment variables:

export API_BASE_URL="https://your-api-base-url"
export BEARER_TOKEN="your-bearer-token"
# Alternative authentication options (use only one):
# export API_KEY="your-api-key"
# export BASIC_AUTH="your-basic-auth-credentials"

Running the MCP Server

STDIO Mode (Default)

The server runs in STDIO mode by default, which is perfect for direct integration with AI assistants like Cursor:

python main.py

Configuration for Cursor/Claude Desktop

Add this to your MCP configuration file (e.g., ~/Library/Application Support/Cursor/User/globalStorage/@anthropic/mcp-server-registry/mcp.json):

{
  "mcpServers": {
    "github-v3-rest-api-mcp-server": {
      "command": "python",
      "args": ["/path/to/your/project/main.py"],
      "env": {
        "API_BASE_URL": "https://your-api-base-url",
        "BEARER_TOKEN": "your-bearer-token"
      }
    }
  }
}

Environment Variables

Required

• API_BASE_URL: Base URL for the API endpoint

Authentication (use one of the following)

• BEARER_TOKEN: Bearer token for OAuth2/Bearer authentication
• API_KEY: API key for API key authentication
• BASIC_AUTH: Basic authentication credentials (base64 encoded)

Note: At least one authentication variable should be provided unless the API explicitly doesn't require authentication.

Development

For development with auto-reload:

# Install development dependencies
pip install -r requirements.txt

# Run with Python
python main.py

Project Structure

.
├── main.py              # Entry point with FastMCP server
├── config.py            # Configuration management
├── models.py            # Pydantic data models
├── tools/               # Auto-generated tools organized by category
│   ├── __init__.py
│   └── [category]/      # Tools grouped by API endpoint category
│       ├── __init__.py
│       └── *.py         # Individual tool implementations
├── requirements.txt     # Python dependencies
└── README.md           # This file

How It Works

This MCP server is built using FastMCP with a decorator-based architecture:

1. FastMCP Server: Creates an MCP server instance in main.py
2. Tool Decorators: Each tool is decorated with @mcp.tool() for automatic registration
3. Auto-Import: Tools are automatically registered when their modules are imported
4. Type Safety: Uses Python type hints for parameter validation
5. Error Handling: Comprehensive error handling with JSON error responses

Example Tool

from main import mcp

@mcp.tool()
def get_users(search: str = None, page: int = None) -> str:
    """
    Get users from the API.
    
    Args:
        search: Search query for filtering users
        page: Page number for pagination
        
    Returns:
        JSON string with user data
    """
    # Tool implementation...
    return json.dumps(result, indent=2)

Authentication Methods

The server supports multiple authentication methods:

Bearer Token (OAuth2)

export BEARER_TOKEN="your-bearer-token"

API Key

export API_KEY="your-api-key"

Basic Authentication

export BASIC_AUTH="base64-encoded-credentials"

Logging

The server includes comprehensive logging to stderr:

• INFO level: General operations, tool registration
• WARNING level: Skipped operations, missing parameters
• ERROR level: API errors, request failures

View logs in your MCP client's console or stderr output.

Troubleshooting

"Missing required parameter" errors

• Check that all required parameters are provided
• Verify parameter names match the tool definition

Authentication errors

• Ensure the correct authentication environment variable is set
• Verify your credentials are valid and not expired
• Check that the API_BASE_URL is correct

Import errors

• Run pip install -r requirements.txt to ensure all dependencies are installed
• Check that you're using Python 3.10 or later

Tool not found

• Verify the tool name matches what's shown in your MCP client
• Check the tools directory structure
• Ensure all __init__.py files are present

Generated Tools

This server was automatically generated from an OpenAPI specification. Each API endpoint is exposed as an MCP tool with:

• Automatic parameter extraction and validation
• Type-safe parameter handling
• Comprehensive error handling
• JSON response formatting

Use your MCP client's tool listing feature to see all available tools.

Contributing

This is a generated MCP server. To modify tool behavior:

1. Edit the tool implementation in tools/[category]/[tool_name].py
2. Maintain the @mcp.tool() decorator for registration
3. Keep the function signature for parameter validation
4. Test changes by running the server locally

License

This generated MCP server follows the same license as the generator tool.