home / mcp / github projects mcp server

GitHub Projects MCP Server

Provides tools to manage GitHub Projects V2 via MCP, including listing, viewing fields, items, and performing create, update, and delete operations.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "arclio-github-projects-mcp": {
      "command": "uvx",
      "args": [
        "mcp-github-projects"
      ],
      "env": {
        "GITHUB_TOKEN": "YOUR_GITHUB_TOKEN"
      }
    }
  }
}

You can run a GitHub Projects V2 MCP Server to manage GitHub Projects V2 data through MCP clients. It provides tools to list projects, view fields and items, create and attach issues, manage draft issues, update item fields, and delete items, all via a unified MCP interface.

How to use

Connect to the MCP server from your MCP client and pick the server configuration that matches how you want to run it. You can run the server locally using the standard runtime tool for MCPs, or run it directly from a development copy of the project. With the appropriate environment variable in place, you gain access to GitHub Projects V2 data and actions such as listing projects, viewing fields, creating issues, attaching issues to projects, editing item fields, and deleting items.

How to install

Prerequisites: you need a working development environment with Python installed, and the command runner tools required by your chosen setup. The server uses Python and a runtime helper to execute MCP commands.

Option A: Use a published package with a local runtime helper.

1. Ensure you have a GitHub Personal Access Token with the required permissions (repo, project, read:org) and keep it secure.

2. Add a server configuration to your MCP client using the published package runner. The example uses the runtime helper to run the MCP server.

3. Start the MCP server configuration in your client so you can begin querying and manipulating GitHub Projects V2 data.

Additional sections

Configuration notes for MCP include explicit server connections and any required environment variables. Ensure you provide a token with the necessary permissions and wire the server into your MCP client configuration exactly as shown in the examples.

Security note: treat your GitHub Personal Access Token as a secret. Do not hard-code it in shared files. Use environment variables or secret management features in your environment.

Examples and options for running from source or from a published package are shown below to illustrate two common workflows. Use the approach that matches your setup.

{
  "mcpServers": {
    "github-projects": {
      "command": "uvx",
      "args": [
        "mcp-github-projects"
      ],
      "env": {
        "GITHUB_TOKEN": "your_pat_here"
      }
    }
  }
}

Or run directly from a source copy with a local directory and the same token.

{
  "mcpServers": {
    "github-projects": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/github-projects-mcp",
        "run",
        "mcp-github-projects"
      ],
      "env": {
        "GITHUB_TOKEN": "your_pat_here"
      }
    }
  }
}

Available tools

list_projects

List GitHub Projects V2 for a given user or organization, showing available projects and basic metadata.

get_project_fields

Retrieve the set of fields available in a GitHub Project V2 to understand what can be configured or filtered on.

get_project_items

Fetch items within a project, with support for filtering by state and by custom single-select fields.

create_issue

Create a new GitHub issue and attach it to a specified Project V2.

add_issue_to_project

Add an existing GitHub issue to a specific Project V2.

update_project_item_field

Update a field value for a project item to reflect changes in status or attributes.

create_draft_issue

Create a draft issue directly within a GitHub Project V2, allowing planning without a public issue.

delete_project_item

Remove an item from a GitHub Project V2.