F8ai/github-mcp

GitHub Projects MCP Server

Model Context Protocol (MCP) server for managing GitHub Projects v2, syncing with Issues, Agents, and TODO.md files.

Overview

This MCP server provides tools and resources for:

• Syncing GitHub Issues to Projects
• Syncing agent configurations to Projects
• Syncing TODO.md files to Projects
• Bidirectional sync between Projects and local files
• Managing Project items via MCP

Perfect for AI-assisted project management and Kanban board synchronization.

Features

• ✅ List and manage GitHub Projects (organization and repository level)
• ✅ Sync GitHub Issues to Project Kanban board
• ✅ Sync Agents from config to Project as tasks
• ✅ Sync TODO.md tasks to Project
• ✅ Sync Project items back to TODO.md
• ✅ Create and update Project items
• ✅ Query project items and status
• ✅ Support for both organization and repository projects

Quick Setup

1. Install Dependencies

npm install

2. Configure Environment

Copy .env.example to .env:

cp .env.example .env

Edit .env and add your values:

GITHUB_TOKEN=your_token_here
GITHUB_OWNER=F8ai
GITHUB_REPO=formul8-multiagent
GITHUB_PROJECT_NUMBER=2

3. Create GitHub Project (if needed)

Option A: Via Web UI (Easiest)

1. Go to: https://github.com/orgs/F8ai/projects/new
2. Click "New project"
3. Select "Board" template
4. Name your project
5. Note the project number from URL (e.g., #2)

Option B: Via Script

export GITHUB_TOKEN=your_token_with_project_scope
./create-org-project.sh

4. Sync Data

# Full sync (all sources → project)
npm run sync

# Or sync individually
npm run sync:issues      # GitHub Issues → Project
npm run sync:agents      # Agents config → Project
npm run sync:todo        # TODO.md → Project

Usage

CLI Commands

# Full sync (all sources → project)
npm run sync

# Sync specific sources
npm run sync:issues      # GitHub Issues → Project
npm run sync:agents      # Agents config → Project
npm run sync:todo        # TODO.md → Project

# Reverse sync (Project → TODO.md)
npm run sync:from-project

# Start MCP server
npm start

MCP Server Tools

The MCP server provides these tools:

1. list_projects - List all GitHub Projects
2. get_project - Get project details and fields
3. list_project_items - List all items in project
4. sync_issues_to_project - Sync issues to Kanban
5. sync_agents_to_project - Create agent tasks
6. sync_todo_to_project - Parse TODO.md and create items
7. sync_project_to_todo - Update TODO.md from project
8. create_project_item - Create new item
9. update_project_item - Update existing item

MCP Integration

To use with MCP clients (like Claude Desktop), add to your MCP config:

{
  "mcpServers": {
    "github-projects": {
      "command": "node",
      "args": ["/absolute/path/to/github-mcp/src/index.js"],
      "env": {
        "GITHUB_TOKEN": "your_token",
        "GITHUB_OWNER": "F8ai",
        "GITHUB_REPO": "formul8-multiagent",
        "GITHUB_PROJECT_NUMBER": "2"
      }
    }
  }
}

GitHub Token Setup

Your GitHub token needs these scopes:

• ✅ repo - Repository access
• ✅ project - Create/manage projects
• ✅ read:project - Read project data
• ✅ read:org - Read organization info (for org projects)

Get/Update Token:

1. Go to: https://github.com/settings/tokens
2. Generate new token or edit existing
3. Select required scopes
4. Copy token to .env file

Project Structure

github-mcp/
├── src/
│   ├── index.js          # MCP server main file
│   ├── sync.js           # Sync functions
│   ├── sync-cli.js       # CLI sync tool
│   └── project-helper.js # Project helper functions
├── package.json
├── .env.example
├── .env                  # Your config (gitignored)
├── create-org-project.sh # Create org project script
├── README.md             # This file
└── LICENSE               # MIT License

Syncing Strategy

Issues → Project

• All open issues are added to the project
• Issues can be filtered by labels
• Existing issues in project are skipped

Agents → Project

• Each agent from config/agents.json creates an issue
• Issues are labeled with agent, mvp, and the agent ID
• Issues include agent description, specialties, and keywords

TODO.md → Project

• Parses markdown to extract - [ ] tasks
• Groups by section (## headings)
• Creates issues for incomplete tasks
• Preserves section hierarchy

Project → TODO.md

• Reads project items
• Groups by labels
• Updates TODO.md with current status
• Preserves formatting

Troubleshooting

Authentication Errors

• Verify GITHUB_TOKEN in .env is correct
• Check token has required scopes (project, read:project, read:org)
• Token may have expired - generate a new one

Project Not Found

• Verify GITHUB_PROJECT_NUMBER matches your project
• Check project exists: https://github.com/orgs/F8ai/projects
• Ensure project is in the correct organization

GraphQL Errors

• Rate limiting: Wait and retry (5000 requests/hour for authenticated users)
• Invalid field names: Check project field names match
• Missing permissions: Ensure token has project and read:org scopes

Rate Limits

GitHub API has rate limits. If you hit limits:

• Wait a few minutes
• Run sync commands individually
• Consider batching operations

Development

Adding New Sync Sources

1. Create a new sync function in src/sync.js
2. Add a tool handler in src/index.js
3. Update this README

Testing

# Test MCP server
npm start

# Test sync functions
npm run sync

License

MIT License - see file for details.

Repository

https://github.com/F8ai/github-mcp