Which integrations are available for this server?

Provides tools for linting, formatting, and auto-fixing Python code using the Ruff linter.

How do I use ruff-mcp-server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@ruff-mcp-server lint the file src/main.py" 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.

ruff-mcp-server

by drewsonne

Overview Schema Related Servers Score Discussions

Python

Local

Ruff MCP Server

An MCP (Model Context Protocol) server providing comprehensive Ruff linting, formatting, and code analysis tools with advanced logging capabilities.## Usage

Installation

# Install from source (recommended for development)
pip install -e .

# Or install directly
pip install .

Running the MCP Server

After installation, you can start the server using any of these methods:

# Method 1: Use the installed command (recommended)
ruff-mcp-server

# Method 2: Run as Python module
python -m ruff_mcp_server

# Method 3: Use convenience script
./scripts/run_server.sh

# Method 4: Run directly from source
python src/ruff_mcp_server/main.py

Command Line Options

# Disable online documentation fetching (use static docs only)
ruff-mcp-server --no-online-docs

# Configure logging
ruff-mcp-server --log-level DEBUG                    # Set log level
ruff-mcp-server --log-file /path/to/logfile.log      # Log to file
ruff-mcp-server --no-console-log                     # Disable console logging

# Combined example: Debug mode with file logging
ruff-mcp-server --log-level DEBUG --log-file ./logs/ruff-mcp-debug.log

# Show help
ruff-mcp-server --help

MCP Client Configuration

The server uses stdio communication (not HTTP ports). Configure your MCP client with:

{
  "servers": {
    "ruff-mcp-server": {
      "command": "ruff-mcp-server",
      "args": ["--log-level", "INFO"]
    }
  }
}

Server Status: When running, you'll see:

============================================================
🚀 RUFF MCP SERVER  
============================================================
📡 Communication: Standard I/O (stdin/stdout)
🔗 Protocol: Model Context Protocol (MCP)  
📚 Online Docs: Enabled
🛑 Shutdown: Press Ctrl+C for graceful shutdown
============================================================

See docs/MCP_CONFIGURATION.md for detailed configuration examples and troubleshooting.

Configuration Philosophy

The Ruff MCP server follows a stateless, agent-driven configuration approach:

No Server-Side Config: The server doesn't store default Ruff configurations
Agent Provides Context: The AI agent passes configuration with each request
Auto-Discovery: When no config is specified, Ruff automatically finds pyproject.toml or ruff.toml in the project
Flexible Overrides: Agents can override specific settings (rules, line length) per request

Example: Agent-Driven Configuration

{
  "name": "ruff_check",
  "arguments": {
    "path": "src/",
    "config_path": "pyproject.toml",     // Use project's config
    "select": ["F", "E4", "W"],         // Focus on specific rule categories  
    "ignore": ["E203", "W503"]          // Ignore specific rules
  }
}

This approach ensures the server respects the agent's workspace context and project-specific requirements.

Testing the Server

Test scripts are provided to verify the server works correctly:

# Test basic server functionality
python test_server.py

# Test logging system
python test_logging.py

Logging & Monitoring

The Ruff MCP Server includes comprehensive logging capabilities for debugging, monitoring, and performance analysis.

Quick Logging Setup

# Basic logging to console (default)
ruff-mcp-server

# Debug mode with file logging
ruff-mcp-server --log-level DEBUG --log-file ./logs/ruff-mcp-debug.log

# Production mode - warnings and errors only
ruff-mcp-server --log-level WARNING --log-file /var/log/ruff-mcp.log --no-console-log

Log Categories

Server Operations: Startup, shutdown, tool management
Tool Execution: Individual tool performance and results
Ruff Commands: Command execution with timing
Documentation: Online documentation fetching and caching
Performance: Automatic execution time tracking

Detailed Logging Guide

See docs/LOGGING.md for comprehensive logging documentation including:

Log levels and categories
Performance monitoring
Production monitoring setup
Debug techniques
Log analysis examples

Using with MCP Clients

The server implements the Model Context Protocol and can be used with any MCP-compatible AI coding assistant. Configure your client to connect to this server and you'll have access to the following tools:

ruff_check - Lint Python files and get detailed violation reports
ruff_format - Format Python code or check formatting
ruff_fix - Automatically fix linting violations where possible

Example Tool Usage

Linting a file

{
  "name": "ruff_check",
  "arguments": {
    "path": "my_script.py",
    "format": "json"
  }
}

Formatting code

{
  "name": "ruff_format", 
  "arguments": {
    "path": "my_script.py",
    "check_only": false
  }
}

Auto-fixing violations

{
  "name": "ruff_fix",
  "arguments": {
    "path": "my_script.py",
    "unsafe": false
  }
}
```rver that provides Ruff linting and code analysis tools for AI coding assistants.

## Features

- 🔧 **Ruff Integration**: Run linting and formatting through MCP tools
- 📊 **Code Analysis**: Detailed code quality reports and suggestions
- � **Inline Documentation**: Get immediate explanations and fix suggestions for violations
- �🛠️ **Configurable**: Support for custom Ruff configurations
- 🚀 **Fast**: Leverages Ruff's speed for real-time analysis

## Tools Provided

### `ruff_check`
Run Ruff linting on files or directories
- **Parameters**: `path` (file or directory), `config_path` (optional)
- **Returns**: Linting results with violations and suggestions

### `ruff_format`
Format Python code using Ruff
- **Parameters**: `path` (file or directory), `check_only` (optional)
- **Returns**: Formatted code or formatting diff

### `ruff_fix`
Auto-fix linting violations where possible
- **Parameters**: `path` (file or directory), `unsafe` (optional)
- **Returns**: Applied fixes and remaining violations

## Installation

```bash
# Clone the repository
git clone <repository-url>
cd ruff-mcp-server

# Install dependencies
pip install -e .

# Or install with development dependencies
pip install -e ".[dev]"

Related MCP server: mcp-lint-tools

Usage

Running the MCP Server

# Start the server
ruff-mcp-server

# Or run with custom configuration
ruff-mcp-server --config /path/to/ruff.toml

Connecting to AI Clients

Add this server to your MCP client configuration:

{
  "mcpServers": {
    "ruff": {
      "command": "ruff-mcp-server",
      "args": []
    }
  }
}

Configuration

You can customize Ruff behavior by providing a configuration file:

ruff-mcp-server --config pyproject.toml
# or  
ruff-mcp-server --config ruff.toml

See ruff.toml.example for a sample configuration file.

Development

Setup Development Environment

# Clone the repository
git clone <repository-url>
cd ruff-mcp-server

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"

Running Tests

# Test the MCP server
python test_server.py

# Check code quality
ruff check .
ruff format .

Extending Rule Documentation

The server includes inline documentation for common Ruff rules in the get_rule_documentation() function in main.py. To add documentation for additional rules:

Find the rule code (e.g., "E401", "F401")
Add an entry to the rule_docs dictionary with a helpful explanation
Focus on providing actionable fix suggestions rather than just describing the problem

Example:

"E401": "Combine multiple imports on separate lines. Use 'import os, sys' → 'import os\\nimport sys'"

Features

✅ Fast and Reliable: Built on Ruff's lightning-fast Python linter and formatter
✅ MCP Compatible: Works with any Model Context Protocol client
✅ Rich Output: Beautifully formatted violation reports with emojis and inline documentation
✅ Inline Help: Provides immediate explanations and fix suggestions for each violation
✅ Configurable: Supports all Ruff configuration options
✅ Error Handling: Robust error handling with helpful error messages
✅ Multiple Formats: Supports JSON, text, GitHub, GitLab, JUnit, and SARIF output formats

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE file for details.

Available Tools

4 tools

pytest_runnerB

Run pytest tests on specific files, test functions, or entire test suite

ParametersJSON Schema

Name	Required	Description	Default
`path`	No	Path to test file or directory (optional, defaults to current directory)	.
`capture`	No	Capture mode: 'no' (disable), 'sys' (capture stdout/stderr), 'fd' (capture file descriptors)	sys
`markers`	No	Run tests with specific markers (e.g., '-m slow' or '-m "not slow"')
`maxfail`	No	Stop after N test failures
`verbose`	No	Run with verbose output (-v flag)
`extra_args`	No	Additional pytest arguments
`test_class`	No	Specific test class to run (e.g., 'TestMyClass')
`last_failed`	No	Run only tests that failed in the last run (--lf flag)
`collect_only`	No	Only collect tests, don't run them (--collect-only flag)
`failed_first`	No	Run failed tests first, then remaining tests (--ff flag)
`test_pattern`	No	Test pattern to match (e.g., 'test_*_integration')
`very_verbose`	No	Run with very verbose output (-vv flag)
`test_function`	No	Specific test function to run (e.g., 'test_my_function')

TDQS

B3.2/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It only states 'Run pytest tests' without disclosing behavioral traits such as side effects (e.g., no file modification), required dependencies, or how results are returned. The description adds minimal insight beyond the name.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence with no wasted words. It is front-loaded with the core action and resource.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 13 optional parameters and no output schema, the description is too minimal. It does not explain how parameters interact (e.g., test_function vs test_class), default behavior when no parameters are provided, or what the output looks like. For a complex testing tool, more detail is needed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3. The description does not elaborate on parameter meanings beyond what the schema already provides, nor does it explain relationships or typical usage patterns. It adds no extra value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Run pytest tests') and the resource ('specific files, test functions, or entire test suite'), distinguishing it from the sibling ruff_* tools which are for linting and formatting.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives. While the purpose distinguishes it from siblings, there is no mention of prerequisites, context, or when not to use it (e.g., if pytest is not installed).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

ruff_checkC

Run Ruff linting on files or directories

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes	Path to file or directory to check
`format`	No	Output format (json, text, etc.)	json
`ignore`	No	Rules to ignore (e.g., ['E203', 'W503']). Overrides config file.
`select`	No	Rules to enable (e.g., ['E4', 'W', 'F']). Overrides config file.
`config_path`	No	Path to Ruff configuration file. If not provided, Ruff will auto-discover config files (pyproject.toml, ruff.toml) in the project directory.

TDQS

C2.6/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so description carries full burden. It provides zero behavioral traits: no error handling, output format description, performance notes, or side effects beyond stating it runs linting.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single sentence is concise but under-specified for a tool with 5 parameters and sibling context. Lacks structure or front-loading of key details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite high schema coverage, the description lacks contextual details such as output behavior, error cases, and usage scenarios relative to siblings. Incomplete for a 5-parameter tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, all parameters have clear descriptions. The tool description adds no additional meaning beyond the schema, meeting the baseline expectation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the action ('Run') and resource ('Ruff linting') on files or directories. It distinguishes from sibling tools like ruff_fix or ruff_format by focusing on linting, but does not explicitly name them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus siblings (ruff_fix, ruff_format). No prerequisites, limitations, or context provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

ruff_fixB

Auto-fix linting violations where possible

ParametersJSON Schema

Name	Required	Description
`path`	Yes	Path to file or directory to fix
`unsafe`	No	Apply unsafe fixes (use with caution)
`config_path`	No	Path to Ruff configuration file (optional)

TDQS

B3.3/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description bears full responsibility for disclosing behavioral traits. It mentions 'auto-fix' but does not clarify that this modifies files (destructive behavior), nor does it explain what 'where possible' means (some violations may be unfixable). The 'unsafe' parameter is named but its implications are not described.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence, very concise. It earns its place by clearly stating the core purpose. However, it could include a bit more context without becoming overly verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has 3 parameters and no output schema, yet the description provides no information about return values, behavior (e.g., modifies files in place), or safety considerations. Given the presence of sibling tools, the description does not help the agent decide when to use this tool. Completeness is insufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the input schema already describes all parameters. The description adds no additional meaning beyond the schema. Baseline score of 3 is appropriate as the description does not compensate for any gaps.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Auto-fix linting violations where possible'. It uses a specific verb ('fix') and resource ('linting violations'), and the name 'ruff_fix' together with the description distinguishes it from sibling tools like 'ruff_check' (check only) and 'ruff_format' (formatting).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides minimal usage guidance. It implies the tool is for automatically fixing linting issues, but does not explicitly state when to use this tool over alternatives like 'ruff_check' or 'ruff_format'. No conditions, prerequisites, or exclusions are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

ruff_formatC

Format Python code using Ruff

ParametersJSON Schema

Name	Required	Description
`path`	Yes	Path to file or directory to format
`check_only`	No	Only check if files need formatting, don't format
`config_path`	No	Path to Ruff configuration file. If not provided, Ruff will auto-discover config files (pyproject.toml, ruff.toml) in the project directory.
`line_length`	No	Maximum line length. Overrides config file setting.

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description bears full responsibility for disclosure. It states 'Format Python code' but does not clarify that files are modified in-place, whether changes are reversible, or if any safety checks are performed. The agent lacks critical behavioral context for a mutation operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence with no redundancy. Extremely concise and front-loaded, every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having 4 parameters and no output schema, the description does not explain return values (e.g., what is output after formatting?), side effects (file modification), or error behavior. This is insufficient for a tool that modifies files, especially without annotations to fill gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already covers all parameters (100% coverage). The description adds minimal value beyond the schema, such as explaining the auto-discovery behavior for config_path. For line_length and check_only, the description essentially repeats schema documentation. Overall, marginal enrichment.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool formats Python code using Ruff. The verb 'Format' and resource 'Python code' are specific, and it distinguishes from sibling tools like ruff_check and ruff_fix by focusing on formatting, though it could explicitly mention that it applies code style.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives like ruff_check or ruff_fix. There is no mention of typical use cases, prerequisites, or scenarios where formatting is appropriate.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

4 tool updatesv0.1.0Jul 6, 2026
- First observedpytest_runner
- First observedruff_check
- First observedruff_fix
- First observedruff_format

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3.3/5.0

Disambiguation5/5

Each tool targets a distinct action: running tests, lint-checking, auto-fixing, and formatting. No overlap in purpose.

Naming Consistency4/5

Tools consistently use snake_case and an action-oriented pattern, but 'pytest_runner' deviates from the 'ruff_*' prefix used by the others, causing minor inconsistency.

Tool Count5/5

Four tools is a tight, well-scoped set covering the core Python development workflows of testing and linting/formatting.

Completeness4/5

Covers the essential operations for the domain: test execution, linting, auto-fix, and formatting. Minor gaps like custom rule configuration are absent, but the core is complete.

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Danushkumar-V-mcp-discordOAuth
ai.smithery
An MCP server that integrates with Discord to provide AI-powered features.
Communication Social Media App Automation
2
docs
dev.continue
An MCP server for docs.continue.dev
Documentation Access Developer Tools Search
2
secureflows-mcp A
io.github.michal-lefler
MCP server for secureFlows: token-free URL builders and integration-linting tools for AI agents.
Code Analysis Developer Tools Security
181
gread A
io.github.NitroRCr
An MCP server that gives your AI access to the source code and docs of all public github repos
Version Control Code Analysis Documentation Access
5361

Related MCP Servers

mcp-server-analyzer
Code Analysis Developer Tools
Anselmoo
A
license
A
quality
A
maintenance
An MCP server that performs comprehensive Python code analysis using Ruff, ty, and Vulture for linting, type checking, and dead code detection.
Updated 6 days ago (2026-08-30 20:48 UTC)
8
10
MIT
mcp-lint-tools
Code Analysis Testing & QA Tools
rog0x
A
license
Not graded
quality
D
maintenance
Code linting and style checking tools for AI agents, exposed as an MCP server. Supports style checks, naming conventions, complexity analysis, dead code detection, and import analysis.
Updated 6 months ago (2026-03-21 20:21 UTC)
63
MIT
Project Customization MCP
Developer Tools Code Analysis
e1imba
A
license
Not graded
quality
D
maintenance
An open-source MCP server that automates project customization by analyzing your codebase and generating AI-ready configuration files based on industry best practices.
Updated 7 months ago (2026-02-02 09:56 UTC)
21
MIT
python-mcp
Code Analysis Developer Tools
yriveiro
A
license
A
quality
C
maintenance
This MCP server provides direct access to ruff linting, formatting checks, and ty type-checking for Python projects, with token-efficient, structured output.
Updated a month ago (2026-08-10 15:03 UTC)
9
MIT

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/drewsonne/ruff-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server