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
Documentation
Community
Recognition
License

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.

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

https://github.com/user-attachments/assets/4225ab98-ae2f-46dc-b3ce-7d117e552b8c

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

Phase 2: Implementation

https://github.com/user-attachments/assets/2aaee9f1-3592-438a-a633-255b5cbbb8e1

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

Installation

Quick Start

Prerequisites:

Node.js >= 18.12.0
GitHub authentication (choose one):
- GitHub CLI (recommended): https://cli.github.com/
- Personal Access Token: Create at github.com/settings/tokens with scopes: repo, read:user, read:org

Using GitHub CLI:

Install the GitHub CLI if you haven’t already: https://cli.github.com/
Authenticate with your GitHub account:

gh auth login

Add Octocode MCP to your MCP configuration:

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

Using Personal Access Token:

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

Using Claude CLI:

Make sure the GitHub CLI is installed and authenticated:

gh auth login

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

More Examples

Additional Demonstrations

ThreeJS Implementation Quality Comparison

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

Deep Technical Research

YouTube: React Hooks Internals

Demonstrates progressive research workflow:

Repository discovery (React source)
Structure exploration (hooks implementation)
Code analysis (internal mechanisms)
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

Architecture

System Design

┌─────────────────────────────────────────────────────────────┐
│                     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                                │
└─────────────────────────────────────────────────────────────┘

Data Flow

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

Octocode MCP Server

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

Purpose

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

Research Tools

Tool	Purpose	Key Parameters	Output
githubSearchCode	Find code implementations across repositories	`keywordsToSearch`, `owner`, `repo`, `path`, `extension`	Code snippets with match context
githubSearchRepositories	Discover repositories by topic/keywords	`topicsToSearch`, `keywordsToSearch`, `stars`, `language`	Repository metadata (stars, topics, description)
githubViewRepoStructure	Explore directory structure	`owner`, `repo`, `path`, `depth`	File tree with sizes
githubGetFileContent	Read file contents with smart extraction	`owner`, `repo`, `path`, `matchString`, `startLine`, `endLine`	File content (full or partial)
githubSearchPullRequests	Analyze PRs, changes, discussions	`owner`, `repo`, `state`, `merged`, `withContent`	PR metadata, diffs, comments

Full Documentation →

Features

Progressive Research Workflow

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

Advanced Configuration

Tool Selection

# 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"

Environment Variables

Variable	Type	Description	Default
`GITHUB_TOKEN`	string	Personal Access Token for authentication	Uses `gh` CLI
`TOOLS_TO_RUN`	string	Comma-separated list of tools to run exclusively	All default tools
`ENABLE_TOOLS`	string	Comma-separated list of additional tools to enable	None
`DISABLE_TOOLS`	string	Comma-separated list of tools to disable	None
`BETA`	"0" \| "1"	Enable experimental features	"0"

Note: TOOLS_TO_RUN is mutually exclusive with ENABLE_TOOLS/DISABLE_TOOLS.

Documentation

Comprehensive Guides

Resource	Description	Link
Official Website	Interactive tutorials, demos, community	octocode.ai
Usage Guide	20+ real-world examples and best practices	USAGE_GUIDE.md
Authentication Guide	Setup instructions and troubleshooting	AUTHENTICATION.md
Tool Schemas	Complete API reference for all tools	TOOL_SCHEMAS.md
Architecture	System design, performance, internals	summary.md
YouTube Channel	Video tutorials and demonstrations	Octocode on YouTube

Community

Get Support

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

Show Your Support

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

License

MIT - See LICENSE for details.

Octocode