aditira/github-project-mcp

GitHub Projects MCP Server

A Model Context Protocol (MCP) server that provides seamless integration between Claude Desktop and GitHub Projects V2. This tool enables you to manage GitHub organization projects, track status updates, and perform project operations directly from Claude conversations.

🌟 Features

Project Management

• List Organization Projects: Fetch all projects from any GitHub organization
• Detailed Project View: Get comprehensive project information including items, fields, and metadata
• Create New Projects: Set up new projects with customizable privacy settings
• Search Projects: Find projects by title across your organization

Status Updates

• View Status History: Retrieve all status updates for any project
• Create Status Updates: Add new progress updates with timeline and status tracking
• Timeline Management: Set start dates, target dates, and project status

Advanced Features

• Real-time Error Handling: Comprehensive error reporting and debugging
• GraphQL Integration: Direct access to GitHub's powerful GraphQL API
• Flexible Configuration: Support for any GitHub organization
• Connection Testing: Built-in diagnostics to verify setup

🚀 Quick Start

Prerequisites

• Python 3.8 or higher
• Claude Desktop application
• GitHub Personal Access Token with appropriate permissions

Installation

1. Clone the repository

   git clone https://github.com/yourusername/github-projects-mcp.git
   cd github-projects-mcp
   

2. Install dependencies

   pip install -r requirements.txt
   

3. Configure environment variables

   cp .env.example .env
   

   Edit .env with your credentials:

   GITHUB_TOKEN=your_github_token_here
   GITHUB_ORG=your_organization_name
   

4. Set up Claude Desktop integration

   Copy the example configuration:

   cp claude_desktop_config-example.json claude_desktop_config.json
   

   Update the paths and credentials in claude_desktop_config.json:

   {
     "mcpServers": {
       "github-projects": {
         "command": "/path/to/your/python",
         "args": ["/path/to/github_projects_mcp.py"],
         "env": {
           "GITHUB_TOKEN": "your_github_token_here",
           "GITHUB_ORG": "your_organization_name"
         }
       }
     }
   }
   

5. Add to Claude Desktop

   Merge the configuration into your Claude Desktop config file (usually located at %APPDATA%\Claude\claude_desktop_config.json on Windows or ~/Library/Application Support/Claude/claude_desktop_config.json on macOS).

GitHub Token Setup

1. Go to GitHub Settings > Personal Access Tokens
2. Click "Generate new token (classic)"
3. Select the following scopes:
   • repo - Full control of private repositories
   • project - Full control of projects
   • read:org - Read org and team membership
4. Copy the generated token to your .env file

📚 Available Tools

Core Project Tools

get_organization_projects(limit=20, include_closed=False)

Retrieve all projects from your GitHub organization with filtering options.

get_project_details(project_number)

Get comprehensive information about a specific project including all items, fields, and metadata.

create_project(title, description="", public=False)

Create a new project in your organization with customizable settings.

Status Management

get_project_status_updates(project_number, limit=20)

Fetch all status updates for a project with author and timeline information.

create_status_update(project_id, body, title=None, start_date=None, target_date=None, status="ON_TRACK")

Add new status updates with support for:

• Markdown content
• Timeline tracking
• Status indicators (ON_TRACK, AT_RISK, OFF_TRACK, COMPLETE)

Utility Tools

search_projects(query, limit=20)

Search projects by title across your organization.

test_connection()

Verify server setup and connection to GitHub API.

💡 Usage Examples

In Claude Desktop

Once configured, you can use natural language to interact with your GitHub projects:

"Show me all projects in our organization"

I'll fetch all the projects from your GitHub organization.

"Get details for project #42"

Let me get the comprehensive details for project #42 including all items and fields.

"Create a new project called 'Q4 Marketing Campaign'"

I'll create a new project with that title in your organization.

"Add a status update to project PVT_kwDOBqF-Dc4AKjQt saying we're on track"

I'll add a status update indicating the project is on track.

🛠️ Technical Details

Architecture

• Built on FastMCP framework for optimal performance
• Uses GitHub GraphQL API v4 for efficient data retrieval
• Implements comprehensive error handling and debugging
• Supports environment-based configuration

API Compatibility

• Fully compatible with GitHub Projects V2
• Handles both organization and repository-level projects
• Supports all major project field types (text, single-select, iteration)
• Real-time synchronization with GitHub's latest schema

Security

• Token-based authentication
• Environment variable protection
• No sensitive data storage
• Secure API communication

🔧 Configuration Options

Environment Variables

Claude Desktop Config

The MCP server integrates with Claude Desktop through the configuration file. Ensure the paths point to your Python installation and the server script location.

🐛 Troubleshooting

Common Issues

"GITHUB_TOKEN not found"

• Ensure your .env file contains the correct token
• Verify the token has required scopes

"Organization not accessible"

• Check the organization name spelling
• Ensure your token has read:org permission
• Verify you're a member of the organization

"GraphQL errors"

• Update your GitHub token permissions
• Check if the organization has enabled Projects V2

Debug Mode

Enable debug mode for detailed logging:

DEBUG_MODE=true

Check Claude Desktop logs for detailed error information.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Development Setup

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the file for details.

🙏 Acknowledgments

• Built with FastMCP framework
• Uses GitHub GraphQL API v4
• Inspired by the Model Context Protocol specification

📞 Support

If you encounter any issues or have questions:

1. Check the Issues section
2. Review the troubleshooting guide above
3. Create a new issue with detailed information about your problem

Made with ❤️ for the Claude Desktop and GitHub Projects community