CodeGraphContext
A powerful MCP server and CLI toolkit that indexes local code into a graph database to provide context to AI assistants and developers. Use it as a standalone CLI for comprehensive code analysis or connect it to your favorite AI IDE via MCP for AI-powered code understanding.
Indexing a codebase
Using the MCP server
Project Details
- Version: 0.1.34
- Authors: Shashank Shekhar Singh shashankshekharsingh1205@gmail.com
- License: MIT License (See LICENSE for details)
- Website: CodeGraphContext
👨💻 Maintainer
CodeGraphContext is created and actively maintained by:
Shashank Shekhar Singh
- 📧 Email: shashankshekharsingh1205@gmail.com
- 🐙 GitHub: @Shashankss1205
- 🔗 LinkedIn: Shashank Shekhar Singh
- 🌐 Website: codegraphcontext.vercel.app
Contributions and feedback are always welcome! Feel free to reach out for questions, suggestions, or collaboration opportunities.
Star History
Features
- Code Indexing: Analyzes code and builds a knowledge graph of its components.
- Relationship Analysis: Query for callers, callees, class hierarchies, call chains and more.
- Pre-indexed Bundles: Load famous repositories instantly with
.cgcbundles - no indexing required! (Learn more) - Live File Watching: Watch directories for changes and automatically update the graph in real-time (
cgc watch). - Interactive Setup: A user-friendly command-line wizard for easy setup.
- Dual Mode: Works as a standalone CLI toolkit for developers and as an MCP server for AI agents.
- Multi-Language Support: Full support for 12 programming languages.
- Flexible Database Backend: FalkorDB Lite (default, inbuilt for Unix and through WSL for Windows) or Neo4j (all platforms via Docker/native).
Supported Programming Languages
CodeGraphContext provides comprehensive parsing and analysis for the following languages:
- Python (
.py) - Including Jupyter notebooks (.ipynb) - JavaScript (
.js) - TypeScript (
.ts) - Java (
.java) - C (
.c,.h) - C++ (
.cpp,.cc,.cxx,.hpp,.hxx) - C# (
.cs) - Full support for classes, methods, namespaces, and inheritance - Go (
.go) - Rust (
.rs) - Ruby (
.rb) - PHP (
.php) - Kotlin (
.kt) - Full support for classes, objects, companions, functions, and coroutines - Swift (
.swift) - Full support for classes, structs, protocols, enums, and generics
Each language parser extracts functions, classes, methods, parameters, inheritance relationships, function calls, and imports to build a comprehensive code graph.
Database Options
CodeGraphContext supports two graph database backends:
FalkorDB Lite (Default for Unix/Linux/macOS)
- Lightweight in-memory graph database
- No external dependencies - runs entirely in-process
- Inbuilt and enabled by default for Unix-based systems (Linux, macOS)
- Available for Python 3.12+ only
- Perfect for quick testing, development, and most use cases
- Automatically installed and configured when using Python 3.12 or higher on Unix systems
⚠️ Windows Users:
FalkorDB Lite / redislite is not supported on Windows.
You have three options:
- Run the project under WSL (Windows Subsystem for Linux): WSL Install
- Use Docker to run the project in a containerized Linux environment
- Use Neo4j directly as your graph database (see below)
Neo4j (Available for All Platforms)
- Production-ready and widely used graph database
- Available on all operating systems: Windows, Linux, macOS
- Can be installed via:
- Docker (recommended, cross-platform)
- WSL (for Windows users)
- Native installation (dedicated command for each OS)
- Supports local instances and cloud hosting (Neo4j AuraDB)
- Full Cypher query support for advanced graph analytics
- Recommended for Windows users and production deployments
The cgc neo4j setup wizard helps you configure the Neo4j database backend, while FalkorDB Lite is enabled by default on Unix systems with no configuration needed.
Used By
CodeGraphContext is already being explored by developers and projects for:
- Static code analysis in AI assistants
- Graph-based visualization of projects
- Dead code and complexity detection
If you’re using CodeGraphContext in your project, feel free to open a PR and add it here! 🚀
Dependencies
neo4j>=5.15.0watchdog>=3.0.0stdlibs>=2023.11.18typer[all]>=0.9.0rich>=13.7.0inquirerpy>=0.3.4python-dotenv>=1.0.0tree-sitter>=0.21.0tree-sitter-language-pack>=0.6.0pyyamlpytestnbformatnbconvert>=7.16.6pathspec>=0.12.1
Note: Python 3.10-3.14 is supported.
Getting Started
📋 Understanding CodeGraphContext Modes
CodeGraphContext operates in two modes, and you can use either or both:
🛠️ Mode 1: CLI Toolkit (Standalone)
Use CodeGraphContext as a powerful command-line toolkit for code analysis:
- Index and analyze codebases directly from your terminal
- Query code relationships, find dead code, analyze complexity
- Visualize code graphs and dependencies
- Perfect for developers who want direct control via CLI commands
🤖 Mode 2: MCP Server (AI-Powered)
Use CodeGraphContext as an MCP server for AI assistants:
- Connect to AI IDEs (VS Code, Cursor, Windsurf, Claude, etc.)
- Let AI agents query your codebase using natural language
- Automatic code understanding and relationship analysis
- Perfect for AI-assisted development workflows
You can use both modes! Install once, then use CLI commands directly OR connect to your AI assistant.
Installation (Both Modes)
-
Install:
pip install codegraphcontext⚙️ Troubleshooting: In case, command
cgcnot foundIf you encounter "cgc: command not found" after installation, run the PATH fix script:
Linux/Mac:
# Download the fix script curl -O https://raw.githubusercontent.com/CodeGraphContext/CodeGraphContext/main/scripts/post_install_fix.sh # Make it executable chmod +x post_install_fix.sh # Run the script ./post_install_fix.sh # Restart your terminal or reload shell config source ~/.bashrc # or ~/.zshrc for zsh usersWindows (PowerShell):
# Download the fix script curl -O https://raw.githubusercontent.com/CodeGraphContext/CodeGraphContext/main/scripts/post_install_fix.sh # Run with bash (requires Git Bash or WSL) bash post_install_fix.sh # Restart PowerShell or reload profile . $PROFILE -
Database Setup (Automatic for Unix/WSL)
- FalkorDB Lite (Default): If you're on Unix/Linux/macOS/WSL with Python 3.12+, you're done! FalkorDB Lite is already configured.
- Neo4j (Optional/Windows): To use Neo4j instead, or if you're on Windows without WSL, run:
cgc neo4j setup
🛠️ For CLI Toolkit Mode
Start using immediately with CLI commands:
# Index your current directory
cgc index .
# List all indexed repositories
cgc list
# Analyze who calls a function
cgc analyze callers my_function
# Find complex code
cgc analyze complexity --threshold 10
# Find dead code
cgc analyze dead-code
# Watch for live changes (optional)
cgc watch .
# See all commands
cgc help
See the full CLI Commands Guide for all available commands and usage scenarios.
🤖 For MCP Server Mode
Configure your AI assistant to use CodeGraphContext:
-
Setup: Run the MCP setup wizard to configure your IDE/AI assistant:
cgc mcp setupThe wizard can automatically detect and configure:
- VS Code
- Cursor
- Windsurf
- Claude
- Gemini CLI
- ChatGPT Codex
- Cline
- RooCode
- Amazon Q Developer
Upon successful configuration,
cgc mcp setupwill generate and place the necessary configuration files:- It creates an
mcp.jsonfile in your current directory for reference. - It stores your database credentials securely in
~/.codegraphcontext/.env. - It updates the settings file of your chosen IDE/CLI (e.g.,
.claude.jsonor VS Code'ssettings.json).
-
Start: Launch the MCP server:
cgc mcp start -
Use: Now interact with your codebase through your AI assistant using natural language! See examples below.
Ignoring Files (.cgcignore)
You can tell CodeGraphContext to ignore specific files and directories by creating a .cgcignore file in the root of your project. This file uses the same syntax as .gitignore.
Example .cgcignore file:
# Ignore build artifacts
/build/
/dist/
# Ignore dependencies
/node_modules/
/vendor/
# Ignore logs
*.log
MCP Client Configuration
The cgc mcp setup command attempts to automatically configure your IDE/CLI. If you choose not to use the automatic setup, or if your tool is not supported, you can configure it manually.
Add the following server configuration to your client's settings file (e.g., VS Code's settings.json or .claude.json):
{
"mcpServers": {
"CodeGraphContext": {
"command": "cgc",
"args": [
"mcp",
"start"
],
"env": {
"NEO4J_URI": "YOUR_NEO4J_URI",
"NEO4J_USERNAME": "YOUR_NEO4J_USERNAME",
"NEO4J_PASSWORD": "YOUR_NEO4J_PASSWORD"
},
"tools": {
"alwaysAllow": [
"add_code_to_graph",
"add_package_to_graph",
"check_job_status",
"list_jobs",
"find_code",
"analyze_code_relationships",
"watch_directory",
"find_dead_code",
"execute_cypher_query",
"calculate_cyclomatic_complexity",
"find_most_complex_functions",
"list_indexed_repositories",
"delete_repository",
"visualize_graph_query",
"list_watched_paths",
"unwatch_directory"
],
"disabled": false
},
"disabled": false,
"alwaysAllow": []
}
}
}
Natural Language Interaction Examples
Once the server is running, you can interact with it through your AI assistant using plain English. Here are some examples of what you can say:
Indexing and Watching Files
-
To index a new project:
- "Please index the code in the
/path/to/my-projectdirectory." OR - "Add the project at
~/dev/my-other-projectto the code graph."
- "Please index the code in the
-
To start watching a directory for live changes:
- "Watch the
/path/to/my-active-projectdirectory for changes." OR - "Keep the code graph updated for the project I'm working on at
~/dev/main-app."
When you ask to watch a directory, the system performs two actions at once:
- It kicks off a full scan to index all the code in that directory. This process runs in the background, and you'll receive a
job_idto track its progress. - It begins watching the directory for any file changes to keep the graph updated in real-time.
This means you can start by simply telling the system to watch a directory, and it will handle both the initial indexing and the continuous updates automatically.
- "Watch the
Querying and Understanding Code
-
Finding where code is defined:
- "Where is the
process_paymentfunction?" - "Find the
Userclass for me." - "Show me any code related to 'database connection'."
- "Where is the
-
Analyzing relationships and impact:
- "What other functions call the
get_user_by_idfunction?" - "If I change the
calculate_taxfunction, what other parts of the code will be affected?" - "Show me the inheritance hierarchy for the
BaseControllerclass." - "What methods does the
Orderclass have?"
- "What other functions call the
-
Exploring dependencies:
- "Which files import the
requestslibrary?" - "Find all implementations of the
rendermethod."
- "Which files import the
-
Advanced Call Chain and Dependency Tracking (Spanning Hundreds of Files): The CodeGraphContext excels at tracing complex execution flows and dependencies across vast codebases. Leveraging the power of graph databases, it can identify direct and indirect callers and callees, even when a function is called through multiple layers of abstraction or across numerous files. This is invaluable for:
-
Impact Analysis: Understand the full ripple effect of a change to a core function.
-
Debugging: Trace the path of execution from an entry point to a specific bug.
-
Code Comprehension: Grasp how different parts of a large system interact.
-
"Show me the full call chain from the
mainfunction toprocess_data." -
"Find all functions that directly or indirectly call
validate_input." -
"What are all the functions that
initialize_systemeventually calls?" -
"Trace the dependencies of the
DatabaseManagermodule."
-
-
Code Quality and Maintenance:
- "Is there any dead or unused code in this project?"
- "Calculate the cyclomatic complexity of the
process_datafunction insrc/utils.py." - "Find the 5 most complex functions in the codebase."
-
Repository Management:
- "List all currently indexed repositories."
- "Delete the indexed repository at
/path/to/old-project."
Contributing
Contributions are welcome! 🎉
Please see our CONTRIBUTING.md for detailed guidelines.
If you have ideas for new features, integrations, or improvements, open an issue or submit a Pull Request.
Join discussions and help shape the future of CodeGraphContext.