Octocode MCP - Enterprise-Ready GitHub Intelligence

AI-Powered GitHub Analysis for Developers and Organizations

What is Octocode?

Octocode transforms your AI assistant into a code research expert. Built for both individual developers and enterprise organizations, it provides:

🏠 For Individual Developers

• 🔍 Search millions of repositories for real implementations
• 📈 Analyze code patterns from production codebases
• 📚 Extract knowledge from commits, PRs, and issues
• 🔗 Connect packages to their source code automatically
• ⚡ Zero-config setup with GitHub CLI integration

🏢 For Organizations & Enterprises

• 🔒 Enterprise security with comprehensive audit logging
• 👥 Organization access controls with team-based permissions
• 📊 Rate limiting and security monitoring
• 📋 Compliance-ready features (SOC 2, GDPR)
• 🔄 Progressive enhancement - enterprise features activate only when configured
• ⬆️ 100% backward compatibility - no breaking changes for existing users

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

📋 Prerequisites

• Node.js >= 18.12.0 (required) - Download here
• GitHub Authentication (choose one):
  • GitHub CLI (recommended for local development) - Install here
  • GitHub Personal Access Token (required for enterprise/CI) - Create here
• AI Assistant (Claude Desktop, or any MCP-compatible assistant)

🚀 Quick Start (Simple)

# 1) Authenticate with GitHub (recommended)
gh auth login

# 2) Run Octocode
npx octocode-mcp

For complete authentication setup including OAuth, GitHub Apps, and enterprise features, see the authentication guides below.

🔐 Authentication & Configuration

Octocode is an MCP Server that requires GitHub authentication. Choose your setup:

🍎 Local Development (macOS with GitHub CLI)

# 1. Install and authenticate with [GitHub CLI](https://cli.github.com/)
gh auth login

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

🌐 Hosted/Production & Windows (GitHub Token)

# 1. Create Personal Access Token at: https://github.com/settings/tokens
# Scopes needed: repo, read:user, read:org

# 2. Add to your MCP configuration:

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

🏢 Enterprise Setup

For organizations with advanced security, audit logging, and OAuth 2.0 authentication:

{
  "mcpServers": {
    "octocode": {
      "command": "npx", 
      "args": ["octocode-mcp"],
      "env": {
        "GITHUB_TOKEN": "ghp_xxxxxxxxxxxx",
        "GITHUB_ORGANIZATION": "your-org",
        "AUDIT_ALL_ACCESS": "true",
        "RATE_LIMIT_API_HOUR": "5000"
      }
    }
  }
}

Enterprise Features:

• Organization Controls - Restrict access to organization members
• OAuth 2.0 & GitHub Apps - Advanced authentication workflows
• Audit Logging - Complete compliance and security tracking
• Rate Limiting - Configurable API usage limits

📚 Enterprise Documentation:

• Enterprise Setup Guide - Organization policies, audit logging, and security configuration
• OAuth 2.0 Integration - How OAuth authentication works for organizations

📚 Complete Authentication Guides

• 30-Second Setup - Quick reference for all authentication methods
• Complete Authentication Guide - Detailed setup for OAuth, GitHub Apps, and enterprise features

🔗 AI Assistant Integration

Quick Setup with Claude CLI:

claude mcp add -s user octocode npx 'octocode-mcp@latest'

Other MCP-Compatible Assistants: Octocode follows the standard Model Context Protocol, making it compatible with any MCP-enabled AI assistant.

🔍 Core Features

GitHub Analysis Tools

• 🔍 Code Search - Semantic code discovery across repositories with bulk operations
• 📁 Repository Analysis - Structure exploration and metadata extraction
• 🔄 Pull Request Search - Find PRs by criteria with optional diff analysis
• 📝 Commit Search - Track changes and development history
• 📄 File Content Retrieval - Access files with context and smart minification
• 🏗️ Repository Structure - Explore directory trees with intelligent filtering

Package Discovery

• 📦 NPM Package Search - Comprehensive npm registry exploration
• 🐍 Python Package Search - PyPI package discovery with repository links
• 🔗 Repository Linking - Automatic connection between packages and source code

Enterprise Security

• 📊 Audit Logging - Comprehensive event tracking and compliance reporting
• 👥 Organization Controls - Team-based access and membership validation
• ⚡ Rate Limiting - Configurable limits for API, auth, and token requests
• 🔐 Token Security - Encrypted storage and automatic rotation support
• 📋 Policy Enforcement - MFA requirements and repository access controls

🚨 Troubleshooting & Help

Common Issues:

• "No GitHub token found" → See Authentication Quick Reference
• Rate limiting/Enterprise setup → See Complete Authentication Guide
• MCP configuration help → See examples above or Complete Authentication Guide

🔧 Environment Variables

Octocode-MCP supports extensive configuration through environment variables. Here's a complete reference:

🔑 Authentication & Core Settings

🛠️ Available Tools

Example Configurations:

# Enable only code search and file content tools
export TOOLS_TO_RUN="githubSearchCode,githubGetFileContent"

# Enable repository exploration tools
export TOOLS_TO_RUN="githubSearchRepositories,githubViewRepoStructure,packageSearch"

# Enable all GitHub tools (exclude package search)
export TOOLS_TO_RUN="githubSearchCode,githubSearchRepositories,githubGetFileContent,githubViewRepoStructure,githubSearchCommits,githubSearchPullRequests"

# Enable single tool for specific use case
export TOOLS_TO_RUN="githubSearchCode"

🏢 Enterprise & Organization Settings

🔐 OAuth 2.0 Configuration

🤖 GitHub App Configuration

📊 Rate Limiting & Performance

🔍 Tool Management

🛡️ Security & Validation

📝 Audit Logging

🔧 Development & Debugging

📋 Configuration Examples

Basic Setup:

export GITHUB_TOKEN="ghp_xxxxxxxxxxxx"

Enterprise Setup:

export GITHUB_TOKEN="ghp_xxxxxxxxxxxx"
export GITHUB_ORGANIZATION="my-company"
export AUDIT_ALL_ACCESS="true"
export RATE_LIMIT_API_HOUR="5000"
export RESTRICT_TO_MEMBERS="true"

OAuth Setup:

export GITHUB_OAUTH_CLIENT_ID="Iv1.a629723bfced6b0c"
export GITHUB_OAUTH_CLIENT_SECRET="your_client_secret"
export GITHUB_OAUTH_REDIRECT_URI="https://yourapp.com/auth/callback"

GitHub App Setup:

export GITHUB_APP_ID="123456"
export GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----..."
export GITHUB_APP_INSTALLATION_ID="12345678"

Selective Tool Usage:

export TOOLS_TO_RUN="githubSearchCode,githubGetFileContent,githubViewRepoStructure"

📚 Documentation

Quick Links

• 📚 Complete User Guide - Examples and best practices
• 🔐 Authentication Guide - Complete setup for all authentication methods
• ⚡ Quick Setup Reference - 30-second authentication setup
• 🏗️ Technical Architecture - System design and implementation
• 🛠️ Tool Schemas - Complete API reference

📄 License

MIT License - see LICENSE.md for details.

📞 Support

• 📚 Documentation: Complete guides and API reference
• 🐛 Issues: GitHub Issues
• 🏢 Enterprise Support: Contact us
• 💬 Community: Discord