FAQ - fleXRPL/github-mcp GitHub Wiki

Frequently Asked Questions

General Questions

What is the GitHub MCP Server?

The GitHub MCP Server is a Model Context Protocol (MCP) implementation that enables AI assistants to interact with GitHub repositories. It provides a standardized interface for performing common GitHub operations like managing repositories, issues, pull requests, and content.

What is MCP?

Model Context Protocol (MCP) is a protocol that defines how AI assistants can interact with external tools and services. It provides a standardized way for AI models to make tool calls and receive responses, enabling them to perform actions in the real world.

Why use the GitHub MCP Server?

The GitHub MCP Server offers several benefits:

  • Standardized interface for GitHub operations
  • Secure authentication using system keychain
  • Real-time updates via Server-Sent Events
  • Comprehensive tool set for GitHub interactions
  • Easy integration with AI assistants

Installation and Setup

How do I install the server?

You can install the server using pip:

pip install github-mcp

Or from source:

git clone https://github.com/yourusername/github-mcp.git
cd github-mcp
pip install -e .

What are the system requirements?

  • Python 3.8 or higher
  • System keychain access
  • GitHub account
  • Network access to GitHub API

How do I set up authentication?

The server uses githubauthlib for authentication, which automatically handles token management through your system's keychain. No manual token configuration is required.

Can I run the server without a GitHub account?

No, a GitHub account is required as the server interacts with GitHub's API to perform operations.

Usage

How do I start the server?

Run the following command:

python -m github_mcp.server

The server will start on http://localhost:8000 by default.

How do I configure Cursor IDE to use the server?

  1. Open Cursor IDE settings
  2. Navigate to the MCP configuration
  3. Add the server URL: http://localhost:8000/sse
  4. Save the configuration

What tools are available?

The server provides tools for:

  • Repository management
  • Issue management
  • Pull request management
  • Content management

See the Features page for detailed information.

How do I handle rate limiting?

The server automatically respects GitHub's API rate limits and provides rate limit information in response headers. Implement exponential backoff for retries when needed.

Troubleshooting

The server won't start

Common issues and solutions:

  1. Port already in use

    • Check if another process is using port 8000
    • Use a different port with --port option

  2. Authentication failed

    • Ensure GitHub credentials are in system keychain
    • Check GitHub account status
    • Verify network connectivity

  3. Python version mismatch

    • Ensure Python 3.8+ is installed
    • Check virtual environment if used

Tool calls are failing

Common causes:

  1. Invalid parameters

    • Check parameter requirements
    • Verify parameter types
    • Review error messages

  2. Permission issues

    • Verify repository access
    • Check token permissions
    • Review GitHub account settings

  3. Rate limiting

    • Check rate limit headers
    • Implement retry logic
    • Reduce request frequency

Authentication issues

If you're having authentication problems:

  1. Token not found

    • Ensure GitHub credentials are in keychain
    • Try re-authenticating with GitHub
    • Check keychain access permissions

  2. Token expired

    • Tokens are automatically refreshed
    • Check GitHub account status
    • Verify network connectivity

  3. Permission denied

    • Review token permissions
    • Check repository access
    • Verify GitHub account settings

Development

How do I contribute?

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Submit a pull request

See Contributing for detailed guidelines.

How do I add new tools?

  1. Create a new tool handler in github_mcp/tools/
  2. Register the tool in github_mcp/server.py
  3. Add tests in tests/
  4. Update documentation

How do I run tests?

pytest

For specific test files:

pytest tests/test_file.py

How do I debug the server?

  1. Enable debug logging:
python -m github_mcp.server --log-level debug
  1. Use the debug endpoint:
GET /debug
  1. Check logs for detailed information

Security

Is it safe to use?

Yes, the server implements several security measures:

  • Secure token storage in system keychain
  • Input validation
  • Rate limiting
  • HTTPS support
  • Regular security updates

See Security for detailed information.

How are tokens handled?

Tokens are:

  • Stored in system keychain
  • Encrypted at rest
  • Never exposed in logs
  • Automatically refreshed
  • Scoped to minimum required permissions

What about rate limiting?

The server:

  • Respects GitHub's rate limits
  • Implements exponential backoff
  • Provides rate limit information
  • Caches responses when appropriate

Performance

How many requests can it handle?

The server's capacity depends on:

  • GitHub API rate limits
  • Server hardware
  • Network conditions
  • Request complexity

Monitor rate limit headers and implement appropriate caching.

How do I optimize performance?

  1. Caching

    • Implement response caching
    • Use appropriate cache headers
    • Cache frequently accessed data

  2. Request Optimization

    • Batch requests when possible
    • Use appropriate parameters
    • Implement pagination

  3. Server Configuration

    • Adjust worker count
    • Configure timeouts
    • Optimize logging

Support

Where can I get help?

  • GitHub Issues
  • GitHub Discussions
  • Documentation
  • Community forums

How do I report bugs?

  1. Check existing issues
  2. Create a new issue
  3. Include:
    • Detailed description
    • Steps to reproduce
    • Expected behavior
    • Actual behavior
    • Environment information

How do I request features?

  1. Check existing issues
  2. Create a new issue
  3. Label as "enhancement"
  4. Describe the feature
  5. Explain the use case

Related Documentation