Content
# 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:
```bash
pip install -r requirements.txt
```
2. Configure environment variables:
```bash
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:
```bash
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`):
```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:
```bash
# 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
```python
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)
```bash
export BEARER_TOKEN="your-bearer-token"
```
### API Key
```bash
export API_KEY="your-api-key"
```
### Basic Authentication
```bash
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.
