mcp-zen-of-languages
An MCP server that gives AI assistants and IDEs multi-language 'zen' code analysis, violation detection, remediation guidance, and project-level reporting.
Analyze code snippets (
analyze_zen_violations) against 348 zen principles with severity scoring, metrics (cyclomatic complexity, maintainability index, LOC), dogma analysis, and optional external linter integration.Scan entire repositories (
analyze_repository) for per-file results with optional language filtering, file caps, and gitignore/.zen-of-languages.ignoreawareness.Run LLM-friendly batch analysis (
analyze_batch,analyze_batch_summary,analyze_batch_auto) with token-budgeted, paginated, highest-severity-first violations and compact health-score/hotspot summaries.Generate remediation prompts (
generate_prompts) with per-file and generic Markdown guidance plus a big-picture roadmap and health trajectory.Create structured agent task lists (
generate_agent_tasks) with priorities, effort estimates, before/after patterns, acceptance criteria, and dependency ordering.Detect architectural patterns (
check_architectural_patterns) such as factory/observer/singleton from code snippets.Produce reports (
generate_report) as Markdown/JSON with gap analysis, prompts, and violation analysis.Manage configuration at runtime (
get_config,set_config_override,clear_config_overrides) for thresholds like max line length, nesting depth, cyclomatic complexity, and severity.Onboard projects (
onboard_project) with recommendedzen-config.yamlsettings and guided setup steps.Discover metadata (
get_supported_languages,detect_languages,export_rule_detector_mapping) to see supported languages, valid keys, and rule/detector coverage.
Provides Zen of Languages analysis for Python source code, detecting idiomatic-code violations, architectural patterns, and generating reports and remediation prompts.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-zen-of-languages Analyze this Python file for best practices"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server for AI assistants that brings multi-language idiomatic code analysis into your editor. Zen of Languages codifies best practices ("zen principles") into machine-readable rules across programming languages, CI automation, and configuration formats — so AI agents and developers get actionable, language-aware feedback in every review. Connect it to Codex, Claude Desktop, VS Code, Cursor, or any MCP-compatible client and start analyzing code in seconds.
350 zen principles across programming, markup, workflow, and config domains
369 detector/check coverage points with severity scoring
MCP server for IDE and agent workflows (13 tools, 3 resources, 1 prompt)
CLI reports with remediation prompts and JSON / Markdown export
Rule-driven pipelines configurable per language and project
Why MCP for Zen Analysis
MCP turns zen analysis from a standalone report into an interactive engineering loop. Instead of copying output between tools, your editor/agent can call zen tools directly, inspect violations in context, generate remediation prompts, and apply fixes in one flow.
Less context switching: analyze, explain, and remediate without leaving your coding session.
Higher-fidelity fixes: prompts are generated from structured violations, not ad-hoc lint text.
Team consistency: MCP workflows make review behavior repeatable across IDEs and agents.
Related MCP server: CodeBase Optimizer
Zen Philosophy
Zen of Languages treats idioms as engineering constraints, not style preferences. Every language guide encodes the practices that make code maintainable in that ecosystem, then scores violations by risk so teams can fix what matters first.
Language-native quality over one-size-fits-all linting.
Architectural feedback beyond formatting checks.
Actionable prioritization through severity-guided remediation.
The project is guided by the 10 Dogmas of Zen — a set of language-agnostic principles that drive every detector and architectural decision. Read the full philosophy document for anti-patterns, rationale, and detector mappings.
Quickstart
# MCP server (IDE/agent workflows)
uvx --from mcp-zen-of-languages mcp-zen-of-languages-server
# CLI without installing (recommended)
uvx --from mcp-zen-of-languages mcp-zen-of-languages-cli --help
# Or install globally
pip install mcp-zen-of-languages
# Analyze a file (CLI)
mcp-zen-of-languages-cli report path/to/file.py
# Analyze a project with remediation prompts (CLI)
mcp-zen-of-languages-cli report path/to/project --include-promptsLegacy aliases remain available after install: zen for the CLI and
zen-mcp-server for the MCP server.
Ignore files during analysis
Directory scans in both CLI and MCP repository analysis honor:
.gitignore.zen-of-languages.ignore
zen init now bootstraps a starter .zen-of-languages.ignore file when one is missing.
Naming Guide
Keep these names distinct to avoid setup confusion:
Package name:
mcp-zen-of-languages(forpip installanduvx --from)Preferred CLI command:
mcp-zen-of-languages-cliPreferred server command:
mcp-zen-of-languages-serverCompatibility aliases:
mcp-zen-of-languages,zen, andzen-mcp-serverMCP client server key:
zen-of-languages(JSON config label in VS Code/Claude/Cursor; use the same label as a quoted TOML table name in Codex)
Installation
MCP Integration
Add the server to your MCP client configuration. For the full setup guide, see MCP Integration.
Claude Desktop — add to claude_desktop_config.json:
{
"mcpServers": {
"zen-of-languages": {
"command": "uvx",
"args": ["--from", "mcp-zen-of-languages", "mcp-zen-of-languages-server"]
}
}
}VS Code — add to .vscode/mcp.json:
{
"servers": {
"zen-of-languages": {
"command": "uvx",
"args": ["--from", "mcp-zen-of-languages", "mcp-zen-of-languages-server"]
}
}
}Cursor — add to .cursor/mcp.json:
{
"mcpServers": {
"zen-of-languages": {
"command": "uvx",
"args": ["--from", "mcp-zen-of-languages", "mcp-zen-of-languages-server"]
}
}
}Codex — add to ~/.codex/config.toml:
[mcp_servers."zen-of-languages"]
command = "uvx"
args = ["--from", "mcp-zen-of-languages", "mcp-zen-of-languages-server"]
enabled = trueCodex loads MCP servers from the global ~/.codex/config.toml file rather than a repo-local workspace config.
One-Click (VS Code)
Method | VS Code | VS Code Insiders |
UVX (native) | ||
Docker (isolated) |
Docker
# MCP server via Docker
docker run --rm -i ghcr.io/anselmoo/mcp-zen-of-languages:latest
# CLI via Docker
docker run --rm ghcr.io/anselmoo/mcp-zen-of-languages:latest mcp-zen-of-languages-cli --helpCLI — First Code Anamnesis
The CLI is a powerful tool for first code anamnesis — an initial diagnostic sweep of any codebase. Before wiring up MCP or choosing which files to focus on, run a single command to get a full-project health picture with severity-ranked violations, architectural smells, and remediation guidance.
# Install globally
pip install mcp-zen-of-languages
# Full-project diagnostic in one command
mcp-zen-of-languages-cli report path/to/project --include-prompts
# Export structured results for CI or dashboards
mcp-zen-of-languages-cli report path/to/project --export-json report.json --export-markdown report.mdFrom source:
git clone https://github.com/Anselmoo/mcp-zen-of-languages.git
cd mcp-zen-of-languages
uv sync --group dev --all-extras
# Start the MCP server
mcp-zen-of-languages-server
# Run a CLI report
mcp-zen-of-languages-cli report path/to/file.pyMCP Tools
The server exposes 13 tools, 3 resources, and 1 prompt for AI-assisted code analysis.
Family | Tools | Purpose |
Analysis |
| Idiomatic and structural analysis |
Reporting |
| Remediation guidance, task lists, gap reports |
Configuration |
| Read and tune thresholds at runtime |
Metadata |
| Discover languages, rules, detector coverage |
Onboarding |
| Initialize |
See the full MCP Tools Reference for parameters, return types, and workflow diagrams.
Use Cases
AI Code Review — Call
analyze_zen_violationson a file, thengenerate_promptsfor remediation instructions in a single editor round-trip.Project-Wide Gap Analysis —
analyze_repositoryscans a codebase,generate_reportproduces a Markdown/JSON report, andgenerate_agent_taskscreates a prioritised fix list.One-Click Onboarding —
onboard_projectdetects languages and writes a tunedzen-config.yaml, making analysis immediately project-aware.
Supported Languages
Tier | Languages | Notes |
Stable | Python | Full parser + richest detector coverage |
Beta | Pydantic, FastAPI, Django, SQLAlchemy, TypeScript, React, Angular, Next.js, Go, Rust, JavaScript, Vue | Rule-driven pipelines and framework-aware heuristics |
Experimental | Bash, PowerShell, Ruby, C++, C# | Heuristic detectors |
Data/Config | YAML, TOML, JSON/JSON5, XML, GitHub Actions | Structure, schema, and workflow checks |
Configuration
Analysis pipelines are derived from language zen rules and merged with project overrides in zen-config.yaml. See the Configuration Guide for the full reference.
# Generate reports in multiple formats
zen report path/to/project --export-json report.json --export-markdown report.mdDocumentation
Full documentation is available at anselmoo.github.io/mcp-zen-of-languages.
Contributing
See Adding a Language and Development Guide to get started.
License
Available Tools
16 toolsanalyze_batchAnalyze repository (batch / LLM-safe)ARead-onlyIdempotent
Analyse a repository path and return token-budgeted, paginated violations designed for LLM context windows. Highest-severity violations appear first. Pass the returned cursor to resume from the next page.
Inputs: path (required), language (required), cursor, max_files, +3 more. Returns: Paginated result returned by a single ``analyze_batch`` call. Each invocation o…
analyze_batch_autoAnalyze repository (auto-routing)ARead-onlyIdempotent
Smart entry point for LLM agents: automatically decides between returning all violations at once (small repos) or paginating (large repos). Pass the returned cursor back to continue pagination if has_more is true. Prefer this over manually choosing between analyze_repository and analyze_batch.
Inputs: path (required), language (required), cursor, max_files, +3 more. Returns: Paginated result returned by a single ``analyze_batch`` call. Each invocation o…
analyze_batch_summaryAnalyze repository — batch summaryARead-onlyIdempotent
Return a compact project health score and top-5 hotspot files from a repository scan. Always fits within a single LLM context window. Use this before analyze_batch to decide whether full pagination is needed.
Inputs: path (required), language (required), max_files, enable_external_tools, +1 more. Returns: One-shot health overview for the ``analyze_batch_summary`` tool. Unlike the pag…
analyze_repositoryAnalyze repositoryBRead-onlyIdempotent
Analyze a repository path and return per-file analysis results.
Inputs: repo_path (required), languages, max_files, enable_external_tools, +1 more. Returns: result
analyze_zen_violationsAnalyze zen violations (v2)CRead-onlyIdempotent
Analyze a code snippet against zen rules with stricter request-quality guardrails and richer telemetry metadata.
Inputs: code (required), language (required), project_as, perspective, +3 more. Returns: Primary output produced by every language analyser. A call to ``BaseAnalyzer.an…
check_architectural_patternsCheck architectural patternsARead-onlyIdempotent
Return detected architectural patterns for a code snippet.
Inputs: code (required), language (required). Returns: Bundled response from the architectural-pattern detection pass. The ``analyze_z…
clear_config_overridesClear configuration overridesADestructive
Clear all runtime configuration overrides, reverting to zen-config.yaml defaults.
Inputs: no named parameters. Returns: Read-only snapshot of the server's current configuration state. Returned by ``g…
detect_languagesDetect languagesBRead-onlyIdempotent
Return supported language list for analysis.
Inputs: repo_path (required). Returns: Enumeration of every language the server can currently analyse. The ``list_zen_…
export_rule_detector_mappingExport rule detector mappingARead-onlyIdempotent
Generate rule-detector mapping JSON from the live registry.
Inputs: languages. Returns: object
generate_agent_tasksGenerate agent tasksARead-onlyIdempotent
Convert zen violations into structured agent task lists for automated remediation.
Inputs: repo_path (required), languages, min_severity, enable_external_tools, +1 more. Returns: Top-level container for all agent tasks generated from an analysis batch. This…
generate_promptsGenerate remediation prompts (v2)BRead-onlyIdempotent
Generate remediation prompts with MCP-first guidance metadata and v2 versioned prompt semantics.
Inputs: code (required), language (required), project_as, perspective, +2 more. Returns: Bundle of all remediation prompts produced for a single reporting run. Combines…
generate_reportGenerate reportARead-onlyIdempotent
Generate a markdown/json report with gap analysis and prompts.
Inputs: target_path (required), language, project_as, perspective, +3 more. Returns: Final output of the reporting pipeline. Carries both a human-readable Markdown…
get_configGet current configurationARead-onlyIdempotent
Return the current server configuration including any runtime overrides.
Inputs: no named parameters. Returns: Read-only snapshot of the server's current configuration state. Returned by ``g…
get_supported_languagesGet supported languagesARead-onlyIdempotent
Return list of all languages with zen rules and their detector coverage.
Inputs: no named parameters. Returns: object
onboard_projectOnboard a new projectARead-onlyIdempotent
Get interactive onboarding guidance for setting up zen analysis on a project. Returns recommended configuration based on project characteristics.
Inputs: project_path (required), team_size, strictness, primary_language. Returns: Complete onboarding payload returned by ``onboard_project``. Bundles an ordered…
set_config_overrideSet configuration overrideADestructive
Override configuration values for a specific language at runtime. Overrides persist for the session.
Inputs: language (required), max_line_length, max_class_length, max_nesting_depth, +3 more. Returns: Read-only snapshot of the server's current configuration state. Returned by ``g…
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 16 tools
The repository analysis tools form a confusing cluster: analyze_repository, analyze_batch, analyze_batch_summary, and analyze_batch_auto all analyze a repository but differ in output format, pagination, and token budget. Additionally, detect_languages and get_supported_languages both return language lists with only subtle differences. This overlap creates real ambiguity for an agent despite the descriptive text.
All tool names consistently use a verb_noun structure with snake_case, such as analyze_repository, set_config_override, and onboard_project. The pattern is predictable and easy to navigate.
At 16 tools, the server is slightly over the ideal 3-15 range, but the tools cover distinct aspects of the analysis workflow: snippet analysis, repository analysis, batch processing, reporting, configuration, and onboarding. The count feels justified rather than bloated.
The tool set covers the core workflow of language detection, code and repository analysis, paginated scanning, summarization, remediation prompt generation, agent task creation, and configuration management. Minor gaps exist, such as no explicit rule-listing tool, but the export_rule_detector_mapping and get_supported_languages partially compensate.
Maintenance
Related MCP Connectors
AI code governance and code review for Claude Code, Copilot and Cursor. Checks rules and security.
AI-powered codebase analysis — call graphs, security, dead code, complexity. 150+ tools.
Code intelligence platform for AI agents. 20 tools for architecture, security & impact analysis.
Code intelligence for coding agents: semantic, AST, graph, and full-text search. 279+ languages.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables comprehensive code analysis including quality assessment, security vulnerability detection, refactoring suggestions, complexity calculations, and automatic documentation generation for multiple programming languages.5MIT
- AlicenseNot gradedqualityDmaintenanceProvides comprehensive codebase analysis including project structure evaluation, cross-language duplicate detection, microservices validation, and configuration optimization with AI-powered pattern learning that generates actionable improvement reports.MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to scan code for security and quality issues and receive machine-readable reports with suggested fixes and verification criteria.80 npm2MIT
- AlicenseNot gradedqualityDmaintenanceEnables local code inspection and analysis for clean code practices, best practices, and actionable recommendations without external API calls or modifying the code.51 npm1MIT