cctx-mcp
An MCP server that provides structure-aware code analysis (symbol trees, dependencies, docs) to reduce AI agent token consumption by up to 99%, along with Git commit intelligence.
README
<p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/badge/CCTX%E2%80%93MCP-0F172A?style=for-the-badge&logo=python&logoColor=3B82F6&labelColor=1E293B"> <img src="https://img.shields.io/badge/CCTX%E2%80%93MCP-F1F5F9?style=for-the-badge&logo=python&logoColor=2563EB&labelColor=FFFFFF" alt="CCTX-MCP"> </picture> </p>
<p align="center"> <strong>Cut AI agent token usage by 87%.</strong><br> Structure-aware code analysis via the <a href="https://modelcontextprotocol.io">Model Context Protocol</a> — returns symbol trees, dependencies, and docs instead of raw file contents. </p>
<p align="center"> <a href="https://pypi.org/project/cctx-mcp/"><img src="https://img.shields.io/pypi/v/cctx-mcp?style=flat-square&logo=pypi&logoColor=white&label=PyPI&labelColor=1E293B&color=3B82F6" alt="PyPI"></a> <a href="https://pypi.org/project/cctx-mcp/"><img src="https://img.shields.io/pypi/pyversions/cctx-mcp?style=flat-square&logo=python&logoColor=white&label=Python&labelColor=1E293B&color=3B82F6" alt="Python"></a> <a href="https://github.com/nikondrat/cctx-mcp"><img src="https://img.shields.io/github/stars/nikondrat/cctx-mcp?style=flat-square&logo=github&logoColor=white&label=Stars&labelColor=1E293B&color=3B82F6" alt="Stars"></a> <a href="https://github.com/nikondrat/cctx-mcp/actions"><img src="https://img.shields.io/github/actions/workflow/status/nikondrat/cctx-mcp/ci.yml?style=flat-square&logo=githubactions&logoColor=white&label=CI&labelColor=1E293B&color=3B82F6" alt="CI"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-3B82F6?style=flat-square&labelColor=1E293B" alt="License"></a> <img src="https://img.shields.io/badge/Status-Beta-3B82F6?style=flat-square&labelColor=1E293B" alt="Beta"> </p>
Overview
CCTX-MCP — Code ConTeXt via Model Context Protocol. An MCP server that gives AI agents a structured view of source code without reading entire files.
Built for Claude, Cursor, OpenCode, and any MCP-compatible AI coding tool.
<p align="center"> <code>uvx cctx-mcp</code> · <a href="#%EF%B8%8F-tools">Tools</a> · <a href="#-token-savings">Savings</a> · <a href="#-install">Install</a> </p>
Quick Start
uvx cctx-mcp
Add to your MCP client config:
{
"mcpServers": {
"cctx-mcp": {
"command": "uvx",
"args": ["cctx-mcp"]
}
}
}
Tools
Code Analysis
| Tool | Returns | Replaces | Savings |
|---|---|---|---|
smart_read |
symbol hierarchy, deps, docs, line counts | cat + manual parsing |
~87% |
find_symbols |
symbol locations by name or type | grep -r + file reads |
~99% |
get_dependencies |
all imports of a file in one shot | grep ^import |
~96% |
trace_calls |
every call site with file + line | grep across repo |
~90% |
analyze_project |
language breakdown, file counts, tree | find + wc |
~98% |
get_symbol_summaries |
AI semantic descriptions per symbol | reading implementation | ~85% |
Git & Commits
| Tool | Returns | Replaces | Savings |
|---|---|---|---|
compact_change_intelligence |
structured git diff with intent cues | git diff + git status |
~75% |
draft_commit |
AI-generated conventional commit message | writing from scratch | ~90% |
approve_commit_draft |
executes the commit after review | git add + git commit |
— |
Observability
get_config · get_health · get_version
Token Savings
| Operation | Native | With CCTX-MCP | Savings |
|---|---|---|---|
| Read 500-line file | ~1,500 tokens | ~200 tokens | 87% |
| Find function across project | ~5,000 tokens | ~50 tokens | 99% |
| Understand imports | ~800 tokens | ~30 tokens | 96% |
| Analyze project structure | ~10,000 tokens | ~150 tokens | 98% |
| Git change summary | ~3,000 tokens | ~750 tokens | 75% |
Typical session: 80%+ aggregate savings.
Supported Languages
<p> <img src="https://img.shields.io/badge/Swift-FA7343?style=flat-square&logo=swift&logoColor=white" alt="Swift"> <img src="https://img.shields.io/badge/Python-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python"> <img src="https://img.shields.io/badge/TypeScript-3178C6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript"> <img src="https://img.shields.io/badge/JavaScript-F7DF1E?style=flat-square&logo=javascript&logoColor=black" alt="JavaScript"> <img src="https://img.shields.io/badge/Rust-000000?style=flat-square&logo=rust&logoColor=white" alt="Rust"> <img src="https://img.shields.io/badge/Go-00ADD8?style=flat-square&logo=go&logoColor=white" alt="Go"> <img src="https://img.shields.io/badge/Dart-0175C2?style=flat-square&logo=dart&logoColor=white" alt="Dart"> </p>
Powered by tree-sitter AST — each language has a dedicated parser.
Install
uvx (recommended)
{
"mcpServers": {
"cctx-mcp": {
"command": "uvx",
"args": ["cctx-mcp"]
}
}
}
pip
pip install cctx-mcp
{
"mcpServers": {
"cctx-mcp": {
"command": "python",
"args": ["-m", "code_context.server"]
}
}
}
source
git clone https://github.com/nikondrat/cctx-mcp.git
cd cctx-mcp
uv sync
uv run python -m code_context.server --skip-index
Configuration
| Variable | Default | Description |
|---|---|---|
CC_OLLAMA_URL |
http://localhost:11434 |
Ollama server address |
CC_OPENROUTER_API_KEY |
— | Remote inference key |
CC_LLM_ROUTER |
local-first |
local-first, local-only, remote-first, remote-only |
CC_COMMIT_MODEL |
gemma4:latest |
Local model for commit drafting |
CC_EMBED_MODEL |
nomic-embed-text |
Local model for embeddings |
CC_SEMANTIC_SUMMARIES |
1 |
Enable AI symbol summaries |
Development
uv sync
uv run pytest tests/ -v
Debug Logging
Tool calls are logged to ~/.code-context-cache/debug.jsonl with args, result preview, latency, and status:
tail -f ~/.code-context-cache/debug.jsonl
Set CC_DEBUG_LOG env var to change the log path.
PRs welcome. Open issues.
License
MIT — free for any use.
Recommended Servers
playwright-mcp
A Model Context Protocol server that enables LLMs to interact with web pages through structured accessibility snapshots without requiring vision models or screenshots.
Magic Component Platform (MCP)
An AI-powered tool that generates modern UI components from natural language descriptions, integrating with popular IDEs to streamline UI development workflow.
Audiense Insights MCP Server
Enables interaction with Audiense Insights accounts via the Model Context Protocol, facilitating the extraction and analysis of marketing insights and audience data including demographics, behavior, and influencer engagement.
VeyraX MCP
Single MCP tool to connect all your favorite tools: Gmail, Calendar and 40 more.
graphlit-mcp-server
The Model Context Protocol (MCP) Server enables integration between MCP clients and the Graphlit service. Ingest anything from Slack to Gmail to podcast feeds, in addition to web crawling, into a Graphlit project - and then retrieve relevant contents from the MCP client.
Kagi MCP Server
An MCP server that integrates Kagi search capabilities with Claude AI, enabling Claude to perform real-time web searches when answering questions that require up-to-date information.
E2B
Using MCP to run code via e2b.
Neon Database
MCP server for interacting with Neon Management API and databases
Exa Search
A Model Context Protocol (MCP) server lets AI assistants like Claude use the Exa AI Search API for web searches. This setup allows AI models to get real-time web information in a safe and controlled way.
Qdrant Server
This repository is an example of how to create a MCP server for Qdrant, a vector search engine.