GitHub Issues Manager MCP server

The Github Issues Manager MCP is a server implementation of the Model Context Protocol specification that allows controlling issue management on Github repositories. This implementation enables seamless integration with Github's issue tracking system through a standardized MCP interface.

Installation

You can install the Github Issues Manager MCP server using npm:

npm install -g github-issues-mcp

Alternatively, you can clone the repository and install dependencies:

git clone https://github.com/yourusername/github-issues-mcp.git
cd github-issues-mcp
npm install

Configuration

Before running the server, you need to set up your Github authentication details.

Setting Up Github Token

1. Create a Github Personal Access Token with repo scope at https://github.com/settings/tokens
2. Configure the token using either environment variables or a config file

Using environment variables:

export GITHUB_TOKEN=your_personal_access_token

Or create a .env file in the project root:

GITHUB_TOKEN=your_personal_access_token

Running the Server

Start the MCP server by running:

github-issues-mcp --port 8080

Or if you cloned the repository:

npm start -- --port 8080

The server will start on the specified port (defaults to 3000 if not specified).

Usage Examples

Creating a New Issue

To create a new issue, send a POST request with the appropriate JSON payload:

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "command": "create_issue",
    "repository": "owner/repo",
    "title": "Bug: Application crashes when saving",
    "body": "The application crashes when trying to save a file larger than 1MB.",
    "labels": ["bug", "high-priority"]
  }'

Listing Issues

To list issues from a repository:

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "command": "list_issues",
    "repository": "owner/repo",
    "state": "open",
    "limit": 10
  }'

Updating an Issue

To update an existing issue:

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "command": "update_issue",
    "repository": "owner/repo",
    "issue_number": 42,
    "title": "Updated: Application crashes when saving",
    "body": "Updated description with more details...",
    "state": "closed"
  }'

Adding Comments

To add a comment to an issue:

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "command": "add_comment",
    "repository": "owner/repo",
    "issue_number": 42,
    "body": "I've been able to reproduce this issue on version 1.2.3"
  }'

Command Reference

Available Commands

• create_issue: Creates a new issue in the specified repository
• list_issues: Lists issues from a repository with optional filters
• get_issue: Retrieves a specific issue by number
• update_issue: Updates an existing issue
• add_comment: Adds a comment to an existing issue
• list_comments: Lists comments for a specific issue

Command Parameters

The server supports various parameters for each command:

• repository: The repository in format "owner/repo"
• issue_number: The issue number to operate on
• title: Issue title
• body: Issue description or comment content
• state: Issue state ("open" or "closed")
• labels: Array of label names to apply
• assignees: Array of usernames to assign

Error Handling

The server returns standardized error responses with HTTP status codes and descriptive messages:

{
  "error": true,
  "message": "Repository not found or unauthorized access",
  "status": 404
}

Common error codes include:

• 400: Bad request (missing or invalid parameters)
• 401: Unauthorized (invalid token)
• 404: Resource not found
• 422: Validation error

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.