Octocode MCP

Intelligent Code Context for AI Systems

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.

• See It In Action
• Installation
  • Quick Start
  • Platform-Specific Setup
• More Examples
• Overview
• Architecture
  • Octocode MCP Server
• Features
• Commands
  • /research - Expert Code Research Agent
  • /kudos - Repository Appreciation
  • /use - Quick Reference Guide
• Documentation
• Community
• Recognition
• License

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

The Single 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.

• Do a deep research
• Create a plan document
• Initiate the plan and create the application

Phase 1: Research & Planning

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

Phase 2: Implementation

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

• Node.js >= 18.12.0
• GitHub Authentication (choose one):
  • GitHub CLI (recommended): Install from cli.github.com and run gh auth login
  • Personal Access Token: Create at github.com/settings/tokens with scopes: repo, read:user, read:org

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.

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

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

claude 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"]
    }
  }
}

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

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

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

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

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

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).

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.

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! 🎉

Interactive Demo

Side-by-side comparison showing:

• Generic AI: Basic implementation with common patterns
• Octocode-Enhanced AI: Production-grade implementation with advanced techniques from real projects

Key Differences:

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

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

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.

┌─────────────────────────────────────────────────────────────┐
│                     AI Assistant (Client)                    │
│                  (Claude, Cursor, VS Code)                   │
└────────────────────────┬────────────────────────────────────┘
                         │ MCP Protocol (stdio/SSE)
                         │
┌────────────────────────▼────────────────────────────────────┐
│                   Octocode MCP Server                        │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  Tool Layer (5 Research Tools)                       │  │
│  │  - githubSearchCode                                  │  │
│  │  - githubSearchRepositories                          │  │
│  │  - githubViewRepoStructure                           │  │
│  │  - githubGetFileContent                              │  │
│  │  - githubSearchPullRequests                          │  │
│  └────────────────────┬─────────────────────────────────┘  │
│                       │                                      │
│  ┌────────────────────▼─────────────────────────────────┐  │
│  │  Processing Layer (octocode-utils)                   │  │
│  │  - Content Minification (Terser, CSS, HTML)          │  │
│  │  - JSON to YAML Conversion                           │  │
│  │  - Secret Detection & Sanitization                   │  │
│  │  - Token Optimization                                │  │
│  └────────────────────┬─────────────────────────────────┘  │
│                       │                                      │
│  ┌────────────────────▼─────────────────────────────────┐  │
│  │  GitHub Integration Layer                            │  │
│  │  - Authentication (gh CLI / PAT)                     │  │
│  │  - API Client with Rate Limiting                     │  │
│  │  - Permission-based Access Control                   │  │
│  └────────────────────┬─────────────────────────────────┘  │
└────────────────────────┼────────────────────────────────────┘
                         │
                         │ GitHub REST API v3 + GraphQL
                         │
┌────────────────────────▼────────────────────────────────────┐
│                    GitHub Platform                           │
│  - Public Repositories (100M+)                              │
│  - Private Repositories (permission-based)                  │
│  - Organization Repositories                                │
└─────────────────────────────────────────────────────────────┘

1. Request Phase: AI assistant sends MCP tool request with search parameters
2. Authentication: Server validates GitHub credentials (gh CLI or PAT)
3. Query Execution: Server executes GitHub API requests with rate limiting
4. Content Processing: Raw responses processed through octocode-utils
   • Minification for token efficiency
   • Secret detection and sanitization
   • JSON to YAML conversion for structured data
5. Response Delivery: Optimized, secure content returned to AI assistant

Package: packages/octocode-mcp/ NPM: octocode-mcp Type: Model Context Protocol Server

MCP server providing structured access to GitHub's code ecosystem through five specialized research tools.

Full Documentation →

Octocode implements a three-phase research pattern optimized for deep code understanding:

Phase 1: DISCOVER
├─ githubSearchRepositories
│  └─ Find relevant projects by topic, stars, language
└─ Output: List of candidate repositories

Phase 2: EXPLORE
├─ githubViewRepoStructure
│  └─ Understand project organization and architecture
└─ Output: Directory tree with file sizes

Phase 3: ANALYZE
├─ githubSearchCode
│  └─ Find specific implementations and patterns
├─ githubGetFileContent
│  └─ Deep dive into specific files
└─ githubSearchPullRequests (optional)
   └─ Understand evolution and decision rationale

# Run only specific tools (exclusive mode)
export TOOLS_TO_RUN="githubSearchCode,githubSearchRepositories"

# Enable additional tools (additive mode)
export ENABLE_TOOLS="githubSearchPullRequests"

# Disable specific default tools
export DISABLE_TOOLS="githubViewRepoStructure"

# Enable experimental features
export BETA="1"

Note: TOOLS_TO_RUN is mutually exclusive with ENABLE_TOOLS/DISABLE_TOOLS.

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

Purpose: Systematic code research using decision-tree workflows

When to use:

• Understanding repository workflows: Discover how repositories work, trace specific flows through codebases, and understand technical implementations
• Cross-repository flow analysis: Understand complex flows that span multiple repositories, trace data flows across microservices, or analyze how different repos interact
• Technical flow investigation: Deep-dive into technical flows within or across repositories (even cross-repo dependencies and integrations)
• Real-world code examples: Learn from actual production code implementations, not just documentation or tutorials
• Deep technical investigations: Trace code flows, understand complex implementations, analyze architecture decisions
• Answering team questions: Quickly research Slack/Jira questions about features, APIs, or behavior with code-backed answers
• Bug investigation: Find root causes by analyzing code, commit history, and related PRs
• Organization features: Understand how features work across your private/public repositories
• Pattern discovery: Compare implementations across multiple repos to find best practices
• Documentation validation: Verify docs match actual code behavior

What it does:

• Provides systematic guidance through research stages (discovery → exploration → analysis → synthesis)
• Executes multiple queries in parallel for faster results
• Shows transparent reasoning at each step
• Adapts to different research types: code implementation, documentation validation, pattern comparison, or bug investigation

Usage Examples (by research type):

Technical Research (code-first, understanding implementations):

/research How does React's useState hook work internally?
/research How to build a LangChain application with Express backend and Next.js frontend?

Product Research (docs + code validation):

/research What are the rate limiting features in our API according to docs and actual code?
/research How does authentication work in NextAuth.js? Verify docs against implementation

Pattern Analysis (comparing multiple implementations):

/research Compare state management approaches: Redux vs Zustand vs Jotai
/research How do popular repos handle WebSocket reconnection logic?

Bug Investigation (root cause analysis):

/research Why is the payment webhook failing? Trace the error through payment-service
/research User reports slow dashboard loading - investigate performance issues in myorg/frontend

Key Features:

• Progressive refinement (broad → specific → deep dive)
• Code-as-truth validation (verifies docs against actual implementation)
• Cross-repository pattern analysis (public & private repos)
• Comprehensive synthesis with Mermaid diagrams and cited references
• Perfect for answering technical questions from Slack/Jira with code evidence

Purpose: List and appreciate all GitHub repositories used in your research session

When to use:

• End of a research session to see what repos helped you
• Finding repositories to star and support

What it does:

• Analyzes conversation history
• Identifies all GitHub repositories explored via Octocode tools
• Creates formatted list with links and usage notes
• Reminds you to show appreciation to maintainers

Usage:

/kudos

Output Example:

# Repositories Used in This Research

## ⭐ Repositories Explored

1. **facebook/react** — https://github.com/facebook/react
   Searched for hooks implementation and internals

2. **vercel/next.js** — https://github.com/vercel/next.js
   Explored routing architecture

Purpose: Simple reminder of Octocode MCP capabilities and best practices

When to use:

• Quick refresher on available tools
• Learning key practices for efficient research
• Getting started with Octocode

What it covers:

• Code Discovery: Search repositories, explore structures, find patterns
• Deep Analysis: Read files, analyze PRs with diffs, track commits
• Research Workflow: Progressive refinement methodology
• Key Practices: Bulk queries, partial file access, search-first approach

Usage:

/use

1. Start with /use if you're new to Octocode MCP
2. Use /research for complex, multi-step investigations that need structured guidance
3. Run /kudos at the end of sessions to document sources and show appreciation
4. Commands work in any MCP-compatible client (Claude, Cursor, etc.)

• GitHub Discussions: Ask questions, share ideas
• GitHub Issues: Report bugs, request features
• Documentation: Complete guides and references
• YouTube: Video tutorials and examples

If Octocode helps your AI development workflow:

• Star the repository on GitHub
• Share on social media with #OctocodeMCP
• Write about your experience on your blog
• Create tutorials and share with the community
• Contribute improvements and bug fixes

Recognition

---

Built with care for developers by developers

Website • GitHub • NPM

---

Octocode MCP is an official MCP Community Server

MIT - See LICENSE for details.