Troubleshooting Guide

This guide helps you diagnose and resolve common issues with the MCP GitHub Project Manager.

Quick Diagnosis

Check Server Status

# Test if the server starts successfully
mcp-github-project-manager --verbose

# Check environment variables are set
env | grep -E "GITHUB_|ANTHROPIC_|OPENAI_"

Enable Debug Logging

# Set debug logging
export LOG_LEVEL=debug

# Or in your .env file
LOG_LEVEL=debug

# Then restart the server
mcp-github-project-manager

Verify Configuration

# Check required variables
echo "GITHUB_TOKEN: ${GITHUB_TOKEN:0:10}..."
echo "GITHUB_OWNER: $GITHUB_OWNER"
echo "GITHUB_REPO: $GITHUB_REPO"

Common Issues

Authentication Errors

"Bad credentials"

Symptoms:

Server returns 401 error
"Bad credentials" message in logs

Causes:

Token is invalid, expired, or revoked
Token was copied incorrectly (extra spaces/newlines)

Solutions:

Verify token format:

# Token should start with ghp_, gho_, or github_pat_
echo $GITHUB_TOKEN | head -c 10

Regenerate token:
- Go to GitHub Settings > Developer settings > Personal access tokens
- Delete the old token
- Generate a new token with required scopes
- Update your configuration

Check for copy errors:

# Remove any whitespace
export GITHUB_TOKEN=$(echo "$GITHUB_TOKEN" | tr -d '[:space:]')

"Resource not accessible by integration"

Symptoms:

403 Forbidden error
"Resource not accessible" message

Causes:

Token lacks required scopes
Token doesn't have access to the repository
Using fine-grained token without proper permissions

Solutions:

Check token scopes: Required scopes:
- repo (Full repository access)
- project (Project board access)
- write:org (For organization projects)

Verify repository access:

# Test with curl
curl -H "Authorization: Bearer $GITHUB_TOKEN" \
  https://api.github.com/repos/$GITHUB_OWNER/$GITHUB_REPO

For fine-grained tokens: Ensure these permissions are enabled:
- Repository: Read and write
- Projects: Read and write
- Issues: Read and write

"Not Found" (404)

Symptoms:

404 error when accessing resources
"Not found" message

Causes:

Wrong owner or repository name
Private repository without access
Resource doesn't exist

Solutions:

Verify owner and repo:

# Check values
echo "Owner: $GITHUB_OWNER, Repo: $GITHUB_REPO"

# Test API access
curl -H "Authorization: Bearer $GITHUB_TOKEN" \
  "https://api.github.com/repos/$GITHUB_OWNER/$GITHUB_REPO"

Check repository visibility:
- For private repos, ensure token has repo scope
- For organization repos, ensure you're a member
Verify resource exists:
- Check the project/issue/milestone exists in GitHub UI

Connection Issues

"ECONNREFUSED"

Symptoms:

Connection refused error
Server doesn't respond

Causes:

Server not running
Firewall blocking connection
Wrong port/host

Solutions:

Verify server is running:

# Start the server
mcp-github-project-manager

Check network connectivity:

# Test GitHub API
curl https://api.github.com

Check firewall settings:
- Ensure outbound HTTPS (443) is allowed
- Allow connections to api.github.com

"Timeout" errors

Symptoms:

Operations take too long
Timeout error messages

Causes:

Slow network connection
GitHub API is slow or down
Large response sizes

Solutions:

Check GitHub status: Visit GitHub Status
Reduce request scope:
- Use pagination for large lists
- Filter results where possible
Check network:
```
# Test latency
ping api.github.com
```

Server doesn't start

Symptoms:

No output when starting server
Module not found errors

Causes:

Package not built
Node.js version incompatible
Dependencies not installed

Solutions:

If installed from npm:

# Reinstall the package
npm install -g mcp-github-project-manager --force

If running from source:
```
# Rebuild
npm install
npm run build
```
Check Node.js version:
```
# Requires Node.js 18+
node --version
```

MCP Client Issues

Claude Desktop: Server not appearing

Symptoms:

MCP server not listed in Claude
Tools not available

Solutions:

Verify config file location:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- Linux: ~/.config/Claude/claude_desktop_config.json

Validate JSON syntax:

# Check for JSON errors
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | jq .

Restart Claude Desktop:
- Quit completely (not just close window)
- Reopen Claude Desktop
Check logs:
- View Claude Desktop logs for connection errors

Cursor: Connection failed

Symptoms:

"Connection failed" in Cursor
MCP tools not working

Solutions:

Verify npx can run the package:

npx -y mcp-github-project-manager --help

Try with bunx:

{
  "mcpServers": {
    "github-project-manager": {
      "command": "bunx",
      "args": ["-y", "mcp-github-project-manager"]
    }
  }
}

Check Cursor MCP settings:
- Settings > MCP > Verify configuration

VS Code: Extension not connecting

Symptoms:

MCP extension shows disconnected
Tools not available

Solutions:

Verify MCP extension is installed:
- Check Extensions panel for MCP extension

Check configuration format:

{
  "servers": {
    "github-project-manager": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-github-project-manager"]
    }
  }
}

Check VS Code output:
- View > Output > Select "MCP" from dropdown

Windows-Specific Issues

Symptoms:

Server fails to start on Windows
Command not found errors

Solutions:

Use cmd wrapper in MCP config:

{
  "mcpServers": {
    "github-project-manager": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "mcp-github-project-manager"
      ],
      "env": {
        "GITHUB_TOKEN": "your_token"
      }
    }
  }
}

AI Feature Issues

"AI provider not configured"

Symptoms:

AI tools return configuration error
PRD generation fails

Causes:

No AI API key set
Invalid API key format

Solutions:

Set at least one API key:

export ANTHROPIC_API_KEY=sk-ant-xxxx
# Or
export OPENAI_API_KEY=sk-xxxx

Verify key format:
- Anthropic: starts with sk-ant-
- OpenAI: starts with sk-
- Google: alphanumeric string
- Perplexity: starts with pplx-

"Rate limited"

Symptoms:

429 error responses
"Rate limit exceeded" message

Causes:

Too many requests in short time
API quota exceeded

Solutions:

Wait and retry:
- GitHub: wait 1 minute
- AI providers: check your plan limits
Reduce request frequency:
- Add delays between batch operations
- Use smaller batch sizes
Check API usage:
- GitHub: curl -H "Authorization: Bearer $GITHUB_TOKEN" https://api.github.com/rate_limit
- AI providers: check usage dashboard

Fallback mode active

Symptoms:

AI features work but with reduced quality
"Using fallback provider" in logs

Causes:

Primary AI provider unavailable
API key invalid for primary provider

Solutions:

This is normal behavior: The server automatically falls back to alternative providers
Check primary provider:
- Verify API key is correct
- Check provider status page
- Verify billing/quota status

GitHub API Issues

"Secondary rate limit"

Symptoms:

403 error with abuse message
Operations blocked temporarily

Causes:

Too many concurrent requests
Large mutations in short time

Solutions:

Wait 1-5 minutes: Secondary rate limits are temporary
Reduce concurrency:
- Don't run parallel operations
- Add delays between requests

"GraphQL errors"

Symptoms:

GraphQL query errors
Partial data returned

Causes:

Invalid query parameters
Schema changes
Permission issues

Solutions:

Check parameters:
- Verify project/issue IDs are valid
- Check field names match schema

Update package:

npm update -g mcp-github-project-manager

"Project not found"

Symptoms:

Cannot find project by ID
Project operations fail

Causes:

Invalid project ID format
Project deleted or access revoked

Solutions:

Verify project ID format:
- Projects v2 use GraphQL node IDs (e.g., PVT_xxxxx)
- Get ID from project URL or use list_projects
Check project access:
- Verify you have access in GitHub UI
- Ensure token has project scope

Debug Mode

Enabling Debug Logging

# Via environment variable
export LOG_LEVEL=debug
mcp-github-project-manager

# Via command line
mcp-github-project-manager --verbose

What to Look For

Debug logs show:

API requests and responses
Authentication attempts
Rate limit status
Tool invocation details

Example Debug Output

[DEBUG] GitHub API request: GET /repos/owner/repo
[DEBUG] Response: 200 OK (123ms)
[DEBUG] Rate limit: 4999/5000 remaining
[DEBUG] Tool invocation: create_issue
[DEBUG] Parameters: { title: "...", body: "..." }

Getting Help

Reporting Bugs

When reporting issues, include:

Environment info:

node --version
npm --version
mcp-github-project-manager --version

Debug logs: Run with LOG_LEVEL=debug and capture output
Steps to reproduce: What exactly did you do?
Expected vs actual: What did you expect? What happened?

GitHub Issues

Report bugs and feature requests at: GitHub Issues

Required Information for Bug Reports

**Environment:**
- OS: [e.g., macOS 14.0]
- Node.js: [e.g., v20.10.0]
- Package version: [e.g., 1.0.0]
- MCP client: [e.g., Claude Desktop]

**Description:**
[What happened?]

**Steps to Reproduce:**
1. [First step]
2. [Second step]
3. [See error]

**Expected Behavior:**
[What should have happened?]

**Debug Logs:**

[paste relevant logs here]

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Troubleshooting Guide

Quick Diagnosis

Check Server Status

Enable Debug Logging

Verify Configuration

Common Issues

Authentication Errors

"Bad credentials"

"Resource not accessible by integration"

"Not Found" (404)

Connection Issues

"ECONNREFUSED"

"Timeout" errors

Server doesn't start

MCP Client Issues

Claude Desktop: Server not appearing

Cursor: Connection failed

VS Code: Extension not connecting

Windows-Specific Issues

AI Feature Issues

"AI provider not configured"

"Rate limited"

Fallback mode active

GitHub API Issues

"Secondary rate limit"

"GraphQL errors"

"Project not found"

Debug Mode

Enabling Debug Logging

What to Look For

Example Debug Output

Getting Help

Reporting Bugs

GitHub Issues

Required Information for Bug Reports

See Also

FilesExpand file tree

TROUBLESHOOTING.md

Latest commit

History

TROUBLESHOOTING.md

File metadata and controls

Troubleshooting Guide

Quick Diagnosis

Check Server Status

Enable Debug Logging

Verify Configuration

Common Issues

Authentication Errors

"Bad credentials"

"Resource not accessible by integration"

"Not Found" (404)

Connection Issues

"ECONNREFUSED"

"Timeout" errors

Server doesn't start

MCP Client Issues

Claude Desktop: Server not appearing

Cursor: Connection failed

VS Code: Extension not connecting

Windows-Specific Issues

AI Feature Issues

"AI provider not configured"

"Rate limited"

Fallback mode active

GitHub API Issues

"Secondary rate limit"

"GraphQL errors"

"Project not found"

Debug Mode

Enabling Debug Logging

What to Look For

Example Debug Output

Getting Help

Reporting Bugs

GitHub Issues

Required Information for Bug Reports

See Also