Package Exports
- octocode-mcp
- octocode-mcp/dist/index.js
This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (octocode-mcp) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.
Readme

Octocode MCP
Transform Any AI Assistant Into a Code Research Expert
The missing piece for AI agents that need quality code context. Search millions of repositories, analyze real implementations, and discover proven patterns — all through a secure, token-efficient MCP server.
📑 Table of Contents
- Why Octocode MCP?
- Quick Start
- How to Choose the Right Tool
- Available Tools
- Platform Setup
- Real-World Examples
- Advanced Configuration
- Documentation & Resources
- Community & Support
🎯 Why Octocode MCP?
The Context Gap Problem
Most AI assistants today have generic knowledge but lack deep, contextual understanding of real-world code solutions. When you need to:
- ✅ Implement complex features with proven patterns
- ✅ Debug difficult issues by finding similar solutions
- ✅ Understand how enterprise-scale systems work
- ✅ Learn best practices from production code
- ✅ Create comprehensive technical documentation
You hit a wall. Generic AI knowledge isn't enough.
The Octocode Solution
Octocode MCP bridges this gap by providing AI assistants with real-time access to millions of GitHub repositories, enabling:
Capability | What You Get |
---|---|
🔍 Smart Code Discovery | Find relevant implementations using semantic search across millions of repositories |
📊 Progressive Research | AI-powered workflows that build comprehensive understanding through multiple queries |
🏗️ Ecosystem Understanding | Analyze how real organizations structure complex systems and solve hard problems |
📚 Real-World Examples | Access production code, not toy examples or outdated tutorials |
🔒 Enterprise-Grade Security | Automatic content sanitization, respects GitHub permissions, redacts sensitive data |
⚡ Token-Efficient | Smart content minification reduces token usage by up to 70% |
Perfect For
- 🎨 Code Creation: Get context about patterns, libraries, and implementations before writing code
- 🐛 Complex Bug Fixes: Find real solutions for complex bugs by analyzing how others solved similar issues
- 🏢 Enterprise Solutions: Understand how large-scale systems are architected and maintained
- 📖 Documentation: Enrich technical docs with real, tested code examples
- 🎓 Learning: Discover how experienced developers tackle challenging problems
- 🔍 Technology Research: Research new frameworks, patterns, and best practices
See The Difference
🎯 Live Demo: ThreeJS Code Creation Comparison
This interactive comparison shows how Octocode MCP transforms AI assistants from providing generic code suggestions to delivering expert-level, context-rich implementations.
🚀 Quick Start (2 Minutes)
Prerequisites
- Node.js >= 18.12.0
- GitHub Authentication (choose one):
- GitHub CLI (recommended):
gh auth login
- Personal Access Token: Create at github.com/settings/tokens with
repo
,read:user
,read:org
scopes
- GitHub CLI (recommended):
Installation
Add Octocode MCP to your AI assistant's configuration:
{
"mcpServers": {
"octocode": {
"command": "npx",
"args": ["octocode-mcp@latest"]
}
}
}
Need help finding your config file? See Platform Setup for detailed instructions for Claude Desktop, Cursor, Windsurf, and VS Code.
Using a Personal Access Token? Add it to the env
section (see Platform Setup for examples).
Verify Installation
After setup, try this in your AI assistant:
"Search for React hooks implementations in popular repositories"
If you see search results from GitHub repositories, you're all set! 🎉
🧭 How to Choose the Right Tool
Use this decision tree to select the perfect tool for your task:
📝 What do you want to do?
├─ 🔍 Find code or examples
│ ├─ Know what you're looking for → githubSearchCode
│ └─ Need to discover repositories first → githubSearchRepositories
│
├─ 📂 Explore a repository
│ ├─ See file/folder structure → githubViewRepoStructure
│ └─ Read specific files → githubGetFileContent
│
├─ 📚 Understand changes/history
│ └─ Analyze pull requests → githubSearchPullRequests
│
└─ 🎯 Not sure where to start?
└─ Start broad with githubSearchRepositories → then narrow down
Quick Reference Table
Goal | Tool | What It Returns |
---|---|---|
Find specific code | githubSearchCode |
Code snippets with context |
Discover repositories | githubSearchRepositories |
Repo list with stars, topics |
Explore structure | githubViewRepoStructure |
File/folder tree |
Read files | githubGetFileContent |
Full or partial file content |
Analyze changes | githubSearchPullRequests |
PR details, diffs, discussions |
🛠️ Available Research Tools
Default Tools (Always Enabled)
githubSearchCode
Find specific code implementations across repositories
Best for:
- Finding how a function/class is implemented
- Discovering code patterns and examples
- Researching library usage
Not recommended for:
- Finding repositories (use
githubSearchRepositories
) - Reading full files (use
githubGetFileContent
)
Example Prompts:
- "Find React useEffect cleanup patterns"
- "Show me OAuth2 implementation in Node.js"
- "Search for error handling in GraphQL resolvers"
Arguments:
{
keywordsToSearch: string[]; // Required: Terms to search for
owner?: string; // Filter by repo owner
repo?: string; // Filter by specific repo
path?: string; // Search in specific directory
filename?: string; // Filter by filename
extension?: string; // Filter by file type
limit?: number; // Max results (1-20)
}
githubSearchRepositories
Discover repositories by topic, language, or description
Best for:
- Finding projects in specific domains
- Discovering popular implementations
- Research technology ecosystems
Not recommended for:
- Searching inside code (use
githubSearchCode
) - Reading repository content (use
githubViewRepoStructure
first)
Example Prompts:
- "Find popular React component libraries"
- "Show me microservices examples with high stars"
- "Discover AI agent frameworks"
Arguments:
{
keywordsToSearch?: string[]; // Search in name/description
topicsToSearch?: string[]; // Search by GitHub topics
owner?: string; // Filter by owner
stars?: string; // e.g., ">1000", "100..500"
language?: string; // e.g., "TypeScript"
sort?: string; // "stars" | "forks" | "updated"
limit?: number; // Max results (1-20)
}
githubViewRepoStructure
Explore repository file and folder structure
Best for:
- Understanding project organization
- Finding where specific code lives
- Navigating before reading files
Not recommended for:
- Reading file contents (use
githubGetFileContent
) - Searching across repos (use
githubSearchCode
)
Example Prompts:
- "Show me the structure of the React repository"
- "What's in the src folder of this project?"
- "Explore the components directory"
Arguments:
{
owner: string; // Required: Repository owner
repo: string; // Required: Repository name
path?: string; // Directory path (default: root)
depth?: number; // 1 = current dir, 2 = with subdirs
branch?: string; // Branch name (default: main branch)
}
githubGetFileContent
Read file contents with smart context retrieval
Best for:
- Reading specific files
- Getting code context around matches
- Line-range based reading
Not recommended for:
- Searching across files (use
githubSearchCode
) - Finding files (use
githubViewRepoStructure
)
Example Prompts:
- "Show me the README of this repo"
- "Read the authentication module"
- "Get lines 50-100 of this file"
Arguments:
{
owner: string; // Required: Repository owner
repo: string; // Required: Repository name
path: string; // Required: File path
startLine?: number; // Optional: Start reading from line
endLine?: number; // Optional: End reading at line
matchString?: string; // Optional: Find and return context around match
matchStringContextLines?: number; // Lines of context (default: 5)
branch?: string; // Branch name
}
Advanced Tools (Optional)
githubSearchPullRequests
Analyze pull requests, changes, and discussions
Enable with: export ENABLE_TOOLS="githubSearchPullRequests"
Best for:
- Understanding how features were implemented
- Learning from code review discussions
- Analyzing bug fixes and solutions
Not recommended for:
- Current code search (use
githubSearchCode
) - General repository discovery (use
githubSearchRepositories
)
Example Prompts:
- "Show me recent authentication PRs"
- "Find PRs that fixed performance issues"
- "Analyze how they implemented dark mode"
Arguments:
{
owner?: string; // Repository owner
repo?: string; // Repository name
prNumber?: number; // Specific PR number
state?: "open" | "closed"; // PR state
merged?: boolean; // Only merged PRs
query?: string; // Free-text search
limit?: number; // Max results (1-10)
withContent?: boolean; // Include code diffs
withComments?: boolean; // Include discussions
}
🖥️ Platform Setup
Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json
(macOS) or %APPDATA%\Claude\claude_desktop_config.json
(Windows):
{
"mcpServers": {
"octocode": {
"command": "npx",
"args": ["octocode-mcp@latest"]
}
}
}
With Personal Access Token:
{
"mcpServers": {
"octocode": {
"command": "npx",
"args": ["octocode-mcp@latest"],
"env": {
"GITHUB_TOKEN": "ghp_your_token_here"
}
}
}
}
Restart Claude Desktop to activate.
Cursor
- Open Cursor Settings → Features → MCP Servers
- Click "+ Add New Global MCP Server"
- Enter configuration:
{
"mcpServers": {
"octocode": {
"command": "npx",
"args": ["octocode-mcp@latest"]
}
}
}
- Save and restart Cursor
Access in Cursor: Use the Composer (⌘+L on Mac) and select "Agent" mode to automatically use Octocode tools.
Windsurf
Add to ~/.codeium/windsurf/model_config.json
:
{
"mcpServers": {
"octocode": {
"command": "npx",
"args": ["octocode-mcp@latest"]
}
}
}
Restart Windsurf after configuration.
VS Code
One-Click Installation:
Manual Installation:
Add to User Settings (JSON) — Press Ctrl/Cmd + Shift + P
→ Preferences: Open User Settings (JSON)
:
{
"mcp": {
"servers": {
"octocode": {
"command": "npx",
"args": ["octocode-mcp@latest"]
}
}
}
}
📺 Real-World Examples
Example 1: Deep Code Research
Prompt: "Explain deeply how React hooks work under the hood, using information from code and documents."
Watch the AI use Octocode to:
- Search React repository for hooks implementation
- Analyze the source code structure
- Read specific files for technical details
- Synthesize comprehensive explanation
Example 2: Learn About AI Agents
Goal: Create comprehensive context for building AI agents
Example 3: Review Pull Requests
Goal: Analyze how features are implemented through PR reviews
Example 4: Complex ThreeJS Implementation
See the dramatic difference between generic AI and Octocode-enhanced AI:
This comparison shows how Octocode transforms AI from generic suggestions to expert-level implementations with real-world patterns.
⚙️ Advanced Configuration
Tool Selection
Run Specific Tools Only (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
cannot be combined with ENABLE_TOOLS
/DISABLE_TOOLS
.
Environment Variables
Variable | Description | Default |
---|---|---|
GITHUB_TOKEN |
Personal Access Token for authentication | Uses gh CLI if not set |
TOOLS_TO_RUN |
Comma-separated list of tools to run exclusively | All default tools |
ENABLE_TOOLS |
Comma-separated list of additional tools to enable | None |
DISABLE_TOOLS |
Comma-separated list of tools to disable | None |
BETA |
Enable experimental features | 0 |
Example Configuration with Environment Variables
Claude Desktop Config:
{
"mcpServers": {
"octocode": {
"command": "npx",
"args": ["octocode-mcp@latest"],
"env": {
"GITHUB_TOKEN": "ghp_your_token_here",
"ENABLE_TOOLS": "githubSearchPullRequests"
}
}
}
}
Enterprise Features
Content Sanitization:
- Automatic detection and redaction of API keys, tokens, passwords
- Pattern-based secret detection across 50+ types
- Configurable through security policies
Token Optimization:
- Smart content minification (up to 70% reduction)
- Partial file reading for large files
- Structured, predictable response formats
Access Control:
- Respects your GitHub permissions
- Works with public and private repositories
- Organization-level access support
Rate Limiting:
- Built-in GitHub API rate limit handling
- Automatic retries with exponential backoff
- Progress indicators for long operations
📚 Documentation & Resources
Resource | Description | Link |
---|---|---|
🌐 Official Website | Interactive tutorials and community | octocode.ai |
📺 YouTube Channel | Video tutorials and demos | Octocode on YouTube |
📖 Usage Guide | 20+ examples and best practices | USAGE_GUIDE.md |
🔐 Authentication Guide | Complete setup and enterprise features | AUTHENTICATION.md |
🔧 Tool Schemas | Complete API reference for all tools | TOOL_SCHEMAS.md |
🏗️ Architecture | System design and performance details | summary.md |
📦 NPM Package | Latest releases and changelog | octocode-mcp on NPM |
💬 Community & Support
Get Help
- 💡 Feature Requests: GitHub Discussions
- 🐛 Issues & Bugs: GitHub Issues
- 📖 Documentation: octocode.ai
- 🎓 Video Tutorials: YouTube Channel
Contributing
We welcome contributions! Octocode MCP is open source and community-driven.
- Fork the repository on GitHub
- Create a feature branch:
git checkout -b feature/amazing-feature
- Make your changes with tests
- Run tests:
yarn test
- Submit a pull request
See our Contributing Guide for detailed instructions.
Show Your Support
If Octocode MCP helps you build better AI applications, consider:
- ⭐ Star the repository on GitHub
- 🐦 Share on Twitter with #OctocodeMCP
- 📝 Write a blog post about your experience
- 🎥 Create a tutorial and share with the community