Skip to content

QUICKSTART.md

Latest commit

 

History

History
223 lines (169 loc) · 4.46 KB

QUICKSTART.md

File metadata and controls

223 lines (169 loc) · 4.46 KB

Quick Start Guide

Get the GitHub MCP Server running in 5 minutes.

Prerequisites

  • Node.js 18 or higher
  • GitHub Personal Access Token

Installation

# Install dependencies
npm install

# Build project
npm run build

Setup GitHub Token

  1. Create a GitHub Personal Access Token:

  2. Set the environment variable:

    export GITHUB_TOKEN="ghp_your_token_here"

Run the Server

Start the MCP server locally:

npm run dev

The server is now running and listening on stdio for MCP protocol requests.

Test with Example Client

In a new terminal:

export GITHUB_TOKEN="ghp_your_token_here"
npm run client

You should see:

  • ✅ Connection confirmation
  • 📋 List of 9 available tools
  • 📦 Example PR listing
  • 📝 Example PR details
  • 🔧 Tool schema information

Integration with Cursor

Add to your Cursor MCP settings:

{
  "mcpServers": {
    "github": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-deployable/dist/server/index.js"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

Then restart Cursor and ask:

"List the open PRs in my repository"

Integration with OpenAI

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
import OpenAI from 'openai';

// Connect to MCP server
const client = new Client(
  { name: 'openai-github', version: '1.0.0' },
  { capabilities: {} }
);

const transport = new StdioClientTransport({
  command: 'node',
  args: ['dist/server/index.js'],
  env: { GITHUB_TOKEN: process.env.GITHUB_TOKEN } as Record<string, string>,
});

await client.connect(transport);

// Get tools for OpenAI
const { tools } = await client.listTools();

// Use with OpenAI
const openai = new OpenAI();
const response = await openai.chat.completions.create({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'List open PRs in owner/repo' }],
  tools: tools.map(tool => ({
    type: 'function',
    function: {
      name: tool.name,
      description: tool.description,
      parameters: tool.inputSchema,
    },
  })),
});

// Execute tool if requested
if (response.choices[0].message.tool_calls) {
  const toolCall = response.choices[0].message.tool_calls[0];
  const result = await client.callTool({
    name: toolCall.function.name,
    arguments: JSON.parse(toolCall.function.arguments),
  });
  console.log(result);
}

Deploy to Cloudflare Workers

# Install Wrangler globally
npm install -g wrangler

# Login to Cloudflare
wrangler login

# Set GitHub token as secret
wrangler secret put GITHUB_TOKEN

# Deploy
npm run deploy

Your MCP server is now live at:

https://github-mcp-server.your-subdomain.workers.dev

Testing Tools

List Pull Requests

curl -X POST https://your-worker.workers.dev/invoke \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "list_prs",
    "arguments": {
      "owner": "modelcontextprotocol",
      "repo": "typescript-sdk",
      "state": "open"
    }
  }'

Get PR Details

curl -X POST https://your-worker.workers.dev/invoke \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "get_pr",
    "arguments": {
      "owner": "modelcontextprotocol",
      "repo": "typescript-sdk",
      "pull_number": 1
    }
  }'

Next Steps

Troubleshooting

"GITHUB_TOKEN environment variable is required"

Make sure you've exported the token:

export GITHUB_TOKEN="ghp_your_token_here"

"Permission denied" errors

Your token needs the repo scope. Create a new token with proper permissions.

Tests failing

Ensure all dependencies are installed:

npm install
npm run build
npm test

Can't connect from Cursor

  • Use absolute paths in the configuration
  • Verify the build completed: check dist/server/index.js exists
  • Check Cursor's MCP logs for error messages

Support