GitHub MCP Server

# Quick Start Guide ## Prerequisites 1. **Node.js 20+** - Check your version: ```bash node --version ``` 2. **GitHub Personal Access Token** - Create one at https://github.com/settings/tokens - Required scopes: `repo`, `read:org`, `read:user` ## Setup Steps ### 1. Install Dependencies ```bash npm install ``` ### 2. Set GitHub Token **Option A: Create .env file (Recommended)** ```bash # Copy the example file cp .env.example .env # Edit .env and add your token # GITHUB_TOKEN=ghp_your_token_here ``` **Option B: Environment Variable** ```bash export GITHUB_TOKEN=ghp_your_token_here ``` The `.env` file is automatically loaded and is already excluded from git (in `.gitignore`). ### 3. Build the Project ```bash npm run build ``` This compiles TypeScript to JavaScript in the `dist/` directory. ### 4. Run the Server ```bash npm start ``` The server will start and communicate via stdio. You should see: ``` GitHub MCP server running on stdio ``` ## Development Mode For development with auto-rebuild on file changes: ```bash # Terminal 1: Watch and rebuild npm run dev # Terminal 2: Run server (after first build completes) npm start ``` ## Testing the Server The MCP server communicates via stdio, so it's typically launched by an MCP client. However, you can test it manually in several ways: ### Method 1: Automated Test Script (Recommended) Run the automated test suite: ```bash # Make sure GITHUB_TOKEN is set export GITHUB_TOKEN=your_token_here # Run tests npm run test ``` This will: - Start the server - Test all available tools - Display formatted results - Clean up automatically ### Method 2: Manual Shell Script Use the provided shell script for quick manual testing: ```bash # Make sure GITHUB_TOKEN is set export GITHUB_TOKEN=your_token_here # Run the test script ./test-manual.sh ``` ### Method 3: Direct JSON-RPC Commands Test individual tools with direct commands: ```bash # List available tools echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node dist/mcp/server.js # Get authored PRs echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"github.getAuthoredPRs","arguments":{"username":"octocat","from":"2024-01-01T00:00:00Z","to":"2024-12-31T23:59:59Z"}}}' | node dist/mcp/server.js # Pretty print with jq (optional) echo '...' | node dist/mcp/server.js | grep -v "^Content-Length:" | tail -n +2 | jq '.' ``` ### Method 4: Interactive Testing For more control, use the TypeScript test script: ```bash # Build the test script tsc test-server.ts --outDir dist --module ES2022 --target ES2022 --moduleResolution node --esModuleInterop # Run it node dist/test-server.js ``` ### Example Test Data See `test-examples.json` for a complete list of example requests you can use for testing. ### Testing Tips - **Set GITHUB_TOKEN**: Always set your token before testing - **Use jq**: Install `jq` for pretty JSON output: `brew install jq` - **Check logs**: Server logs appear on stderr - **Real data**: Use actual GitHub usernames and time ranges for meaningful results ## Integration with MCP Clients ### Claude Desktop / Cursor Add to your MCP configuration file (usually `~/Library/Application Support/Claude/claude_desktop_config.json` or similar): ```json { "mcpServers": { "github": { "command": "node", "args": ["/absolute/path/to/github-mcp/dist/mcp/server.js"], "env": { "GITHUB_TOKEN": "ghp_your_token_here" } } } } ``` Or use the provided `mcp.json` as a reference. ## Troubleshooting ### "GITHUB_TOKEN environment variable is required" - Make sure you've set the token: `export GITHUB_TOKEN=your_token` - Verify it's set: `echo $GITHUB_TOKEN` ### "GitHub authentication failed" - Check your token is valid and has the right permissions - Regenerate the token if needed ### "Cannot find module" errors - Run `npm install` to install dependencies - Run `npm run build` to compile TypeScript ### Rate limit errors - The server automatically handles rate limits - Wait for the reset time shown in the error message - Consider using a token with higher rate limits ## Next Steps See `README.md` for: - Detailed tool documentation - Example agent calls - Architecture overview