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


---

---

Table of Contents

- See It In Action
- Installation
- More Examples
- Overview
- Tools
- Commands
- /research - Expert Code & Product Research
- /plan - Research, Plan & Implement Complex Tasks
- /review_pull_request - Comprehensive PR Review
- /review_security - Security Audit
- Documentation
- Community
- License

---

See It In Action

$3

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

---

$3

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

- 🎯 Intelligent Tool Orchestration: Automatically selects and combines the right Octocode tools (repository search, code search, file content, PR analysis, repo structure) based on your research needs
- 🧠 Smart Decision Making: Makes strategic choices throughout the research flow—when to search broadly vs. specifically, which repositories to explore, and how to validate findings
- 👥 Multi-Purpose Research: Perfect for feature discovery (product managers), code understanding (developers), bug investigation, flow analysis, planning from scratch, dependency tracking, security audits, and more
- 🔬 Specialized Workflows: Handles Technical Research (code flows), Product Research (docs+code validation), Pattern Analysis (cross-repo comparison), Bug Investigation, Architecture Mapping, API Research, Security/Auth flows, and more
- 🔍 Transparent Reasoning: Shows you exactly which tools it's using, what it's searching for, and why at each step
- 🎨 Adaptive Strategy: Works across public repos, private organizations, and specific repositories with configurable depth (overview, deep dive, or cross-repo comparison)
- 📊 Cross-Validated Results: Leverages multiple Octocode tools to verify information from different sources and perspectives
- 🚀 Actionable Insights: Delivers implementation-ready plans with code examples, not just raw information

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?

https://github.com/user-attachments/assets/82ed97ae-57a9-46ae-9acd-828a509e711b

---

$3

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:
>
> - Stock market APIs (Typescript)
> - Cursor rules examples
> - UI for AI
> - Mobile development using React
> - State management for React

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.

https://github.com/user-attachments/assets/c184d5d4-c9b6-40a1-a55a-41cb9b3ecc4f

---

Installation

$3

The easiest way to install and configure Octocode is using the interactive CLI:

``bash
npx octocode-cli
`

This will automatically:
- Detect your installed IDEs (Cursor, Claude, Windsurf, etc.)
- Verify your environment (Node.js, GitHub CLI)
- Configure the MCP server correctly for each tool

---

$3

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

See Troubleshooting Guide for common issues and solutions.

---

$3

#### Prerequisites

- 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

$3

First, install the Octocode MCP server with your client.

Standard config works in most of the tools:

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

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

---

$3

Octocode MCP supports two authentication methods:

#### Option 1: GitHub CLI (Recommended)

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

`bash


Install GitHub CLI

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:

`json
{
"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.

---

$3

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.

$3

Add the GITHUB_API_URL environment variable to your MCP configuration:

`json
{
"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 Setup.

---

More Examples

$3

#### 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:
1. Repository discovery (React source)
2. Structure exploration (hooks implementation)
3. Code analysis (internal mechanisms)
4. Comprehensive explanation with code references

---

Commands

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

$3

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:
- 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
- Deep technical investigations: Trace code flows, understand complex implementations, analyze architecture decisions
- Bug investigation: Find root causes by analyzing code, commit history, and related PRs
- Pattern discovery: Compare implementations across multiple repos to find best practices
- Documentation validation: Verify docs match actual code behavior

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
`

---

$3

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:
- Building new features: Research patterns, plan architecture, then implement
- Complex refactoring: Understand current state, plan migration path, execute safely
- Learning new technologies: Research best practices, create learning plan, build incrementally
- System design: Explore existing implementations, design your approach, validate decisions

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
`

---

$3

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:
- Defects & Bugs: Logic errors, edge cases, race conditions, null handling
- Security Issues: Injection vulnerabilities, auth bypasses, data exposure
- Performance: N+1 queries, memory leaks, inefficient algorithms
- Code Quality: Complexity, maintainability, test coverage gaps
- Best Practices: Design patterns, error handling, documentation

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

---

$3

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:
- Authentication & Authorization: Auth flows, session management, access controls
- Input Validation: Injection points, sanitization, boundary checks
- Secrets Management: Hardcoded credentials, API keys, configuration security
- Dependencies: Known vulnerabilities, outdated packages, supply chain risks
- Data Protection: Encryption, PII handling, data flow security

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

---

$3

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

$3

| Resource | Description | Link |
|----------|-------------|------|
| Official Website | Interactive tutorials, demos, community | octocode.ai |
| Configuration Guide | Environment variables and server configuration | CONFIGURATION_REFERENCE.md |
| Authentication Guide | Setup instructions for GitHub & GitLab | Authentication Setup |
| Troubleshooting | Common issues and solutions | Troubleshooting Guide |
| YouTube Channel | Video tutorials and demonstrations | Octocode on YouTube |


---

Community

$3

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

$3

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

---

Privacy & Telemetry

Octocode collects de-identified telemetry data to improve the tool, including command usage and error rates. We never collect source code, environment variables, or PII.

You can opt-out at any time:

`bash
export OCTOCODE_TELEMETRY_DISABLED=1
``

For full details, please read our Privacy Policy and Terms of Usage.

---

License

This project is licensed under the MIT License.

Copyright © 2026 Octocode AI.

See LICENSE for details.