Octocode MCP

AI-Powered GitHub Intelligence for Code Research & Discovery

What is Octocode?

Octocode transforms your AI assistant into a code research expert. Instead of just writing code, your AI can now:

• 🔍 Search millions of repositories for real implementations
• 📈 Analyze code patterns from production codebases
• 📚 Extract knowledge from commits, PRs, and issues
• 🏢 Access private repositories for organizational intelligence
• 🔗 Connect packages to their source code automatically

Built on the Model Context Protocol (MCP), Octocode provides AI assistants with 8 specialized tools for GitHub repository analysis, code discovery, and package exploration.

The Problem: AI assistants are great at writing code but struggle with understanding existing codebases and finding proven patterns.

The Solution: Octocode makes any codebase instantly accessible and comprehensible to AI assistants.

📖 Documentation

Quick Links

• 📚 Usage Guide - Complete guide with examples and best practices
• 🏗️ Technical Architecture - Detailed system architecture and implementation
• 🛠️ Tool Schemas - Complete API reference and tool specifications
• 🌐 Octocode Ecosystem - Explore the complete Octocode suite

💡 Pro Tip: Understanding the tool schemas will significantly improve your Octocode effectiveness.

⚡ Quick Start

Prerequisites

• Node.js v20+ (check with node --version)
• GitHub Authentication (Personal Access Token or GitHub CLI)
• NPM (Optional, enhances package research capabilities)
• AI Assistant (Claude Desktop, or any MCP-compatible assistant)

Authentication Options

Octocode supports flexible GitHub authentication with smart fallback:

1. GitHub CLI (Recommended for local development) - Run gh auth login for seamless authentication
2. Personal Access Token (Recommended for Windows & hosted environments) - Set GITHUB_TOKEN or GH_TOKEN environment variable
3. Authorization Header (For API integrations) - Set Authorization environment variable with Bearer {{token}} format

Performance Optimizations

• NPM Integration: Automatically enhances package research when NPM is available

  For CI/CD environments:

  # As environment variable
  export NPM_TOKEN=your_token_here
  
  # Then in .npmrc:
  //registry.npmjs.org/:_authToken=${NPM_TOKEN}

• PyPI Integration: Discovers Python package repository URLs for comprehensive analysis

🚀 Installation

🚀 Quick Configuration

Option 1: GitHub CLI Authentication 🟢 Recommended

Best for Mac and local development

1. Install and authenticate with GitHub CLI:

   # Install GitHub CLI (if not already installed)
   # macOS: brew install gh
   # Windows: winget install GitHub.cli
   
   # Authenticate
   gh auth login

2. Add to your MCP configuration:

   {
     "octocode": {
       "command": "npx",
       "args": ["octocode-mcp"]
     }
   }

   💡 Tip: This method provides seamless, secure access to your GitHub resources without managing tokens.

Option 2: Personal Access Token

Best for Windows, CI/CD, or hosted environments

1. Create a GitHub token:

   • Go to GitHub Settings → Personal Access Tokens
   • Generate a new token with appropriate permissions

2. Add to your MCP configuration:

   {
     "octocode": {
       "command": "npx",
       "args": ["octocode-mcp"],
       "env": {
         "GITHUB_TOKEN": "your_github_token_here"
       }
     }
   }

Option 3: Authorization Header Format

Best for API integrations and templated configurations

{
  "octocode": {
    "command": "npx",
    "args": ["octocode-mcp"],
    "env": {
      "Authorization": "Bearer your_github_token_here"
    }
  }
}

💡 Note: Supports template formats like Bearer {{GH_TOKEN}} for dynamic token injection.

Authentication Fallback Chain

Octocode uses an intelligent authentication system that tries multiple methods in priority order:

1. GITHUB_TOKEN - Primary GitHub token environment variable
2. GH_TOKEN - Alternative GitHub token environment variable
3. GitHub CLI Token - Automatically extracted from gh auth login session
4. Authorization Header - Extracts token from Bearer format (Bearer {{token}}), supporting template variables

📦 DXT Extension

Desktop Extension (DXT) for one-click installation in Claude Desktop.

yarn install && yarn dxt:pack

Install the generated octocode-mcp.dxt file by clicking on it in Claude Desktop.

Enterprise/Production Deployment

Ideal for: Team environments, Docker containers, CI/CD pipelines, hosted AI services

🐳 Docker Support

Run Octocode MCP in a containerized environment with full GitHub authentication support. Perfect for consistent deployments and team environments.

→ Complete Docker Setup Guide

🛡️ Security & Privacy

Enterprise-Grade Security

• 🛡️ Advanced Content Protection - Multi-layer input validation and intelligent content sanitization
• 🔐 Comprehensive Secret Detection - Automatic detection and redaction of API keys, tokens, and credentials
• ⚪ Safe Commands Only - Pre-approved GitHub CLI and NPM commands with parameter validation
• 🧹 Malicious Content Filtering - Automatic detection and sanitization of harmful code patterns
• 🔍 Security Pattern Analysis - Built-in vulnerability and compliance issue identification

📚 View complete security architecture →

📄 License

MIT License - See LICENSE for details.

Made with ❤️ by the Octocode team