octocode-mcp

A Model Context Protocol (MCP) server enabling AI assistants to search, analyze, and extract insights from millions of GitHub repositories with enterprise-grade security and token efficiency.

Table of Contents

• Quick Start
• Overview
• GitHub Tools
• Local Tools
• Commands
• Octocode CLI
• Installation Guide
• Documentation
• Examples
• Community
• License

Quick Start

Option 1: Octocode CLI (Recommended)

npx octocode-cli

→ Interactive menu for GitHub auth, MCP installation, and AI skills

Option 2: One-Click Install

Option 3: Manual Configuration

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

Overview

Octocode is an agentic code research platform that bridges the gap between AI assistants and real-world code implementations. By providing structured access to GitHub's vast repository ecosystem, it enables AI systems to learn from production codebases rather than relying solely on training data.

Core Capabilities

Packages

Package	npm	Description
octocode-mcp		Core MCP server: GitHub API, local filesystem tools, LSP code intelligence
octocode-cli		Interactive CLI for IDE setup, skills marketplace, MCP management
octocode-vscode	VS Code Marketplace	VS Code extension for OAuth and multi-editor sync
octocode-shared	Internal	Shared utilities for credentials and session management

GitHub Tools

Five specialized tools for comprehensive GitHub code research:

🔍 githubSearchCode

Find code implementations across repositories

• "How do popular repos implement OAuth?"
• "Search for React custom hooks in vercel repos"
• "Find error handling patterns in Express apps"

📚 githubSearchRepositories

Discover repositories by topics and keywords

• "Discover TypeScript CLI tools with >1000 stars"
• "Find all React state management libraries"
• "List all repos from microsoft with topic 'ai'"

🗂️ githubViewRepoStructure

Explore repository directory structure

• "Show me the structure of facebook/react"
• "Explore src/ directory in a monorepo"

📄 githubGetFileContent

Read file contents with smart extraction

• "Get the validateUser function from auth.ts"
• "Read lines 100-150 from the API handler"

🔀 githubSearchPullRequests

Analyze pull requests, changes, and discussions

• "Show recent merged PRs about authentication"
• "Find PRs discussing the API redesign with comments"

Local Tools

Octocode Local provides local filesystem research with LSP-powered code intelligence.

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

Filesystem Tools

LSP Tools (Code Intelligence)

Research Workflows

Discovery:    localViewStructure → localSearchCode → localGetFileContent
Semantic:     localSearchCode → lspGotoDefinition → lspFindReferences
Flow Analysis: localSearchCode → lspCallHierarchy(incoming) → lspCallHierarchy(outgoing)

👉 Full LSP Documentation →

Commands

Intelligent prompt commands that enhance your research workflow:

/research - Expert Code & Product Research

Deep code discovery, documentation analysis, pattern identification, and bug investigation.

When to use:

• Understanding repository workflows and technical implementations
• Cross-repository flow analysis and microservices tracing
• Bug investigation and root cause analysis
• Pattern discovery across multiple repos

/research How does React's useState hook work internally?
/research Compare state management approaches: Redux vs Zustand vs Jotai
/research Why is the payment webhook failing? Trace the error through payment-service

/plan - Research, Plan & Implement Complex Tasks

Your AI architect for complex development work. Breaks down tasks, researches patterns, guides execution.

When to use:

• Building new features with research-backed architecture
• Complex refactoring with migration planning
• Learning new technologies incrementally

/plan Build a real-time chat application with WebSocket support
/plan Migrate our authentication from JWT to OAuth2
/plan Implement a plugin system for our CLI tool

/review_pull_request - Comprehensive PR Review

Args: prUrl (required) - GitHub Pull Request URL

Expert-level PR review with Defects-First mindset. Analyzes:

• Defects & Bugs: Logic errors, edge cases, race conditions
• Security Issues: Injection vulnerabilities, auth bypasses
• Performance: N+1 queries, memory leaks
• Code Quality: Complexity, maintainability, test coverage

/review_pull_request prUrl: https://github.com/facebook/react/pull/12345

/review_security - Security Audit

Args: repoUrl (required) - GitHub repository URL

Comprehensive security analysis. Analyzes:

• Authentication & Authorization: Auth flows, session management
• Input Validation: Injection points, sanitization
• Secrets Management: Hardcoded credentials, API keys
• Dependencies: Known vulnerabilities, supply chain risks

/review_security repoUrl: https://github.com/your-org/your-repo

💡 Pro Tip: Combine /research and /plan — research existing patterns first, then plan your implementation.

Octocode CLI

One-command setup for Octocode, MCP servers, and AI skills across all your IDEs.

npx octocode-cli@latest

🐙 Octocode MCP        - Install/sync Octocode across IDEs
🧠 Manage System Skills - Browse marketplace, install & manage skills  
⚡ Manage System MCP    - Add popular MCP servers to your setup

Learn More: CLI Documentation | What are Skills?

Installation Guide

Prerequisites

• Node.js >= 18.12.0 (or use standalone binary)
• GitHub Authentication: GitHub CLI (recommended) or Personal Access Token

Authentication Methods

# macOS
brew install gh

# Windows
winget install --id GitHub.cli

# Linux - See https://github.com/cli/cli/blob/trunk/docs/install_linux.md

# Authenticate
gh auth login

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

{
  "mcpServers": {
    "octocode": {
      "command": "npx",
      "args": ["octocode-mcp@latest"],
      "env": {
        "GITHUB_TOKEN": "your_token",
        "GITHUB_API_URL": "https://github.company.com/api/v3"
      }
    }
  }
}

IDE-Specific Setup

code --add-mcp '{"name":"octocode","command":"npx","args":["octocode-mcp@latest"]}'

claude mcp add octocode npx octocode-mcp@latest

"amp.mcpServers": {
  "octocode": {
    "command": "npx",
    "args": ["octocode-mcp@latest"]
  }
}

amp mcp add octocode -- npx octocode-mcp@latest

codex mcp add octocode npx "octocode-mcp@latest"

[mcp_servers.octocode]
command = "npx"
args = ["octocode-mcp@latest"]

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

Verify Installation

1. Restart your MCP client completely
2. Check connection status:
   • Cursor: Green dot in Settings → Tools & Integrations → MCP Tools
   • Claude Desktop: Check for "octocode" in available tools
   • VS Code: Verify in GitHub Copilot settings
3. Test: Search GitHub for React hooks implementations

Documentation

Examples

ThreeJS Implementation Quality Comparison

Interactive Demo

Side-by-side comparison showing Generic AI vs Octocode-Enhanced AI implementation quality:

• Performance optimizations from high-performance projects
• Proper resource management patterns
• Industry-standard error handling

Deep Technical Research

YouTube: React Hooks Internals

Progressive research workflow demonstration:

1. Repository discovery (React source)
2. Structure exploration (hooks implementation)
3. Code analysis (internal mechanisms)
4. Comprehensive explanation with code references

Community

Get Support

• GitHub Discussions: Ask questions, share ideas
• GitHub Issues: Report bugs, request features

Show Your Support

If Octocode helps your AI development workflow:

• ⭐ Star the repository on GitHub
• 📣 Share on social media with #OctocodeMCP

License

MIT - See LICENSE for details.