GitHub - bgauryy/octocode-mcp: MCP server for semantic code research and context generation on real-time using LLM patterns | Search naturally across public & private repos based on your permissions | Transform any accessible codebase/s into AI-optimized knowledge on simple and complex flows | Find real implementations and live docs from anywhere (original) (raw)

Octocode Logo

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.

MCP Community Server Ask DeepWiki Trust Score

npm version npm downloads License

Website YouTube Channel

Install in Cursor

MCP Official Servers Awesome MCP Servers

Table of Contents

See It In Action

Full-Stack Application Built in Under 10 Minutes

Watch AI assistant use Octocode to research, plan, and build a complete chat application with Express backend.

Prompt:

Use Octocode MCP for Deep Research

I want to build an application with chat (front-end) that shows a chat window to the user. The user enters a prompt in the chat, and the application sends the prompt to an Express backend that uses AI to process the request.

Add a return box (to show the message returned from the AI) and loaders to the UI. I want to build an AI agent system in Node.js using LangChain and LangGraph. Can you research the latest patterns?

Please conduct thorough research on how to create this in the best way possible. Focus on repositories with good documentation and recent activity.

Phase 1: Research & Planning

Area.mp4

Octocode Plan Document - Detailed architecture and step-by-step guide

Phase 2: Implementation

answer.mp4

Result: Production-ready full-stack application with authentication, real-time features, and best practices - All in less than 10 minutes

Research and Build Fullstack Agentic Application with /research command in Under 10 Minutes

Why use the /research command? Instead of manually searching through repositories and piecing together information, let the AI conduct comprehensive research for you:

Prompt:

/octocode/research How can I use LangChain, LangGraph, and similar open-source AI tools to create agentic flows between agents for goal-oriented tasks? Can you suggest UI frameworks I can use to build a full-stack AI application?

research_s.mp4

Discover APIs, Frameworks, and Dive Into Internal Implementation Details

Octocode excels at both broad discovery and deep code analysis. Whether you're exploring new APIs, finding frameworks, or understanding how popular libraries work under the hood, Octocode provides comprehensive answers in seconds.

First Prompt - Broad Discovery:

list top repositories for:

What happens: Octocode searches across GitHub to find the most popular and well-maintained repositories for each category, analyzing stars, activity, documentation quality, and recent updates. You get curated lists with context about each repository's strengths.

Second Prompt - Deep Implementation Analysis:

How React implemented useState under the hood?

What happens: Octocode dives into React's source code, traces the implementation flow, analyzes the relevant files (ReactHooks.js, ReactFiberHooks.js), and explains the internal mechanics including fiber architecture, hook state management, and dispatcher patterns—all with code references and detailed explanations.

The Power: Move seamlessly from discovering what exists to understanding how it works in a single conversation. No manual repository hunting or code spelunking required.

research_octocode.mp4

Installation

Standalone Binary (No Node.js Required)

curl -fsSL https://raw.githubusercontent.com/bgauryy/octocode-mcp/main/install/install.sh | sh

Full Binary Installation Guide → — Manual downloads, MCP configs, troubleshooting

npm / npx (Requires Node.js)

Prerequisites

Getting started

First, install the Octocode MCP server with your client.

Standard config works in most of the tools:

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

Note: This configuration uses GitHub CLI authentication. For Personal Access Token, see the Authentication Guide below.

Install in VS Code Install in VS Code Insiders

Amp

Add via the Amp VS Code extension settings screen or by updating your settings.json file:

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

Amp CLI Setup:

Add via the amp mcp add command below:

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

Claude Code

Use the Claude Code CLI to add the Octocode MCP server:

claude mcp add octocode npx octocode-mcp@latest

Claude Desktop

Follow the MCP install guide, use the standard config above.

Codex

Use the Codex CLI to add the Octocode MCP server:

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

Alternatively, create or edit the configuration file ~/.codex/config.toml and add:

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

For more information, see the Codex MCP documentation.

Cursor

Click the button to install:

Install in Cursor

Or install manually:

Go to Cursor Settings -> MCP -> Add new MCP Server. Name to your liking, use command type with the command npx octocode-mcp@latest. You can also verify config or add command like arguments via clicking Edit.

Project-Specific Configuration

Create .cursor/mcp.json in your project root:

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

Cline

Add via the Cline VS Code extension settings or by updating your cline_mcp_settings.json file:

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

Gemini CLI

Follow the MCP install guide, use the standard config above.

Goose

Click the button to install:

Install in Goose

Or install manually:

Go to Advanced settings -> Extensions -> Add custom extension. Name to your liking, use type STDIO, and set the command to npx octocode-mcp@latest. Click "Add Extension".

Kiro

Follow the MCP Servers documentation. For example in .kiro/settings/mcp.json:

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

LM Studio

Click the button to install:

Add MCP Server octocode to LM Studio

Or install manually:

Go to Program in the right sidebar -> Install -> Edit mcp.json. Use the standard config above.

opencode

Follow the MCP Servers documentation. For example in ~/.config/opencode/opencode.json:

{ "$schema": "https://opencode.ai/config.json", "mcp": { "octocode": { "type": "local", "command": [ "npx", "octocode-mcp@latest" ], "enabled": true } } }

Qodo Gen

Open Qodo Gen chat panel in VSCode or IntelliJ → Connect more tools → + Add new MCP → Paste the standard config above.

Click Save.

VS Code

Click the button to install:

Install in VS Code Install in VS Code Insiders

Or install manually:

Follow the MCP install guide, use the standard config above. You can also install the Octocode MCP server using the VS Code CLI:

For VS Code

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

After installation, the Octocode MCP server will be available for use with your GitHub Copilot agent in VS Code.

Warp

Go to Settings -> AI -> Manage MCP Servers -> + Add to add an MCP Server. Use the standard config above.

Alternatively, use the slash command /add-mcp in the Warp prompt and paste the standard config from above:

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

Windsurf

Follow Windsurf MCP documentation. Use the standard config above.

Zed

Follow the MCP Servers documentation. Use the standard config above.

Authentication Methods

Octocode MCP supports two authentication methods:

Advantages: Automatic token management, works with 2FA, supports SSO

Install GitHub CLI

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

Then use the standard configuration (no GITHUB_TOKEN needed).

Option 2: Personal Access Token

When to use: CI/CD environments, automation, or if GitHub CLI isn't available

  1. Create a token at github.com/settings/tokens
  2. Select scopes: repo, read:user, read:org
  3. Add to your MCP configuration:

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

Security Tip: Never commit tokens to version control. Use environment variables or secure secret management.

Verify Installation

After installation, verify Octocode MCP is working:

  1. Restart your MCP client completely
  2. Check connection status:
    • Cursor: Look for 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 with a simple query:
Search GitHub for React hooks implementations

If you see Octocode tools being used, you're all set! 🎉

GitHub Enterprise Support

Octocode MCP supports GitHub Enterprise Server instances with custom API URLs.

Configuration

Add the GITHUB_API_URL environment variable to your MCP configuration:

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

Default: If not specified, defaults to https://api.github.com (public GitHub).

Note: Ensure your GitHub Enterprise token has the same scopes as documented in the Authentication Guide.

More Examples

Additional Demonstrations

ThreeJS Implementation Quality Comparison

Interactive Demo

Side-by-side comparison showing:

Key Differences:

Deep Technical Research

YouTube: React Hooks Internals

Demonstrates progressive research workflow:

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

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

Capability Implementation Benefit
Code Discovery Multi-dimensional search across repositories, code, and pull requests Find relevant implementations in seconds
Context Extraction Smart content retrieval with pattern matching and line-range targeting Get exactly the context you need
Token Optimization Advanced minification strategies (50+ language support) 30-70% reduction in token consumption
Security Automatic secrets detection and content sanitization Enterprise-grade data protection
Progressive Research Workflow-driven exploration (Discover → Explore → Analyze) Deep understanding of complex systems
Access Control GitHub permission-based access to public and private repositories Organization-wide code research

Tools

Octocode provides five specialized research tools designed to work together for comprehensive code analysis:

🔍 githubSearchCode

Find code implementations across repositories

Search for specific code patterns, functions, or implementations across millions of repositories.

Key Features:

Common Use Cases:

• Find implementation examples: "How do popular repos implement OAuth?"
• Discover patterns: "Search for React custom hooks in vercel repos"
• Locate functions: "Find error handling patterns in Express apps"

📚 githubSearchRepositories

Discover repositories by topics and keywords

Your starting point for repository discovery - find the right projects to analyze.

Key Features:

Common Use Cases:

• Find popular implementations: "Discover TypeScript CLI tools with >1000 stars"
• Research ecosystems: "Find all React state management libraries"
• Organization research: "List all repos from microsoft with topic 'ai'"

🗂️ githubViewRepoStructure

Explore repository directory structure

Understand how a project is organized before diving into specific files.

Key Features:

Common Use Cases:

• Project overview: "Show me the structure of facebook/react"
• Find entry points: "Explore src/ directory in a monorepo"
• Understand architecture: "Navigate to the API implementation folder"

📄 githubGetFileContent

Read file contents with smart extraction

Retrieve specific content from files efficiently - full files or targeted sections.

Key Features:

Common Use Cases:

• Read specific functions: "Get the validateUser function from auth.ts"
• Extract sections: "Show me all the middleware definitions in app.js"
• Read configuration: "Get the full package.json file"
• Analyze specific code: "Read lines 100-150 from the API handler"

🔀 githubSearchPullRequests

Analyze pull requests, changes, and discussions

Understand how code evolved, why decisions were made, and learn from production changes.

Key Features:

Common Use Cases:

• Learn from changes: "Show recent merged PRs about authentication"
• Understand decisions: "Find PRs discussing the API redesign with comments"
• Track implementations: "See how feature X was implemented with diffs"
• Expert contributions: "Find PRs by @author in the last 6 months"

Full Documentation →

Commands

Octocode MCP provides intelligent prompt commands that enhance your research workflow:

/research - Expert Code & Product Research

Powerful research prompt leveraging Octocode's full capabilities for deep code discovery, documentation analysis, pattern identification, and bug investigation. Orchestrates parallel bulk queries with staged analysis to uncover insights fast.

When to use:

Usage Examples:

/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 tackling complex development work. Breaks down ambitious tasks into actionable steps, researches existing patterns and implementations, then guides you through execution—all powered by Octocode's deep codebase intelligence.

When to use:

Usage Examples:

/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 (e.g., https://github.com/owner/repo/pull/123)

Expert-level PR review with a Defects-First mindset. Dives deep into code changes, spots bugs before they ship, flags complexity risks, and delivers actionable feedback that elevates code quality.

What it analyzes:

Usage:

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

/review_security - Security Audit

Args: repoUrl (required) - GitHub repository URL (e.g., https://github.com/owner/repo)

Comprehensive security analysis of a repository. Identifies vulnerabilities, reviews authentication/authorization patterns, checks for secrets exposure, and provides remediation guidance.

What it analyzes:

Usage:

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

Tips for Using Commands

  1. Use /research for code exploration - Deep dive into how things work
  2. Use /plan for building - Research, plan, then implement complex features
  3. Use /review_pull_request before merging PRs for thorough code review
  4. Use /review_security for security audits of repositories

💡 Pro Tip: Combine /research and /plan for maximum effectiveness—research existing patterns first, then plan your implementation with confidence.

Documentation

Comprehensive Guides

Resource Description Link
Binary Installation Standalone binary download and setup BINARY_INSTALLATION.md
Configuration Guide Environment variables and server configuration CONFIGURATION.md
Authentication Guide Setup instructions and troubleshooting AUTH_GUIDE.md

Local Research

octocode-mcp-local brings the power of Octocode's research capabilities to your local filesystem.

octocode-mcp-local

An MCP server that provides AI assistants with native Unix tools for local code exploration. Built on ripgrep for pattern search, find for file metadata queries, and ls for directory traversal.

Quick Install

Install in Cursor

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

👉 Get Started with Octocode Local

Community

Get Support

Show Your Support

If Octocode helps your AI development workflow:

License

MIT - See LICENSE for details.