pyeye

PyEye 👁️

PyEye Server

An extensible MCP (Model Context Protocol) server that provides intelligent Python code analysis, navigation, and understanding capabilities for AI assistants like Claude.

Features

• 🔍 Semantic Code Navigation: Find symbols, go to definitions, find references using Jedi
• 📊 Module & Package Analysis: List packages/modules, analyze dependencies, detect circular imports
• 🏗️ Multi-Project Support: Analyze multiple projects and dependencies simultaneously
• 📦 Namespace Packages: Handle packages distributed across multiple repositories
• 📝 Standalone Scripts: Analyze notebooks, scripts, and examples alongside formal packages
• 🔄 Auto-Update: Automatically detects and reflects file changes with smart cache invalidation
• ⚙️ Configuration System: Flexible configuration via files, env vars, or auto-discovery
• 🔌 Extensible Plugin System: Framework-specific analyzers (Pydantic, Django, Flask)
• 🚀 Fast & Cached: Intelligent caching with LRU eviction and performance optimization
• 🎯 Type-Aware: Full understanding of Python type hints and annotations
• 📈 Performance Monitoring: Built-in metrics tracking with p50/p95/p99 latencies
• 🛡️ Input Validation: Secure parameter validation and path checking
• 🤖 Development Automation: Release automation, dogfooding metrics, and worktree safety

Installation

PyEye can be installed in three ways: as a Claude Code plugin (zero-config), into your project's venv, or globally.

Option 0: Claude Code Plugin (zero-config)

When PyEye is installed as a Claude Code plugin, dependencies install automatically into a per-user venv on first session start — no manual pip install needed.

• First session start: a SessionStart hook runs uv sync --no-dev --frozen against the plugin checkout, with the venv built at ${CLAUDE_PLUGIN_DATA}/.venv (typically ~/.claude/plugins/data/<plugin-id>/.venv).
• Subsequent sessions: the hook compares uv.lock in the plugin checkout against the last-installed copy in ${CLAUDE_PLUGIN_DATA} and is a silent no-op unless the lockfile changed.
• Requirement: uv must be on your PATH. See uv installation.

Both the install hook and the MCP server invocation use uv run, so this works on Linux, macOS, and Windows without OS-specific configuration.

Option 1: Project-Specific Installation (Recommended)

Install directly into your Python project's virtual environment:

# Activate your project's virtual environment
source /path/to/your/project/venv/bin/activate

# Install from PyPI
pip install pyeye-mcp

# Or install from source
git clone https://github.com/okeefeco/pyeye-mcp.git
pip install -e ./pyeye-mcp

Then create a .mcp.json file in your project root:

{
  "mcpServers": {
    "pyeye": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "pyeye.mcp"],
      "env": {}
    }
  }
}

This way, the MCP server uses your project's environment and has access to all your project's dependencies.

Option 2: Global Installation

For analyzing multiple projects or using with global Python:

# Install globally with pipx (recommended for isolation)
pipx install pyeye-mcp

# Or with pip
pip install --user pyeye-mcp

# Or from source
git clone https://github.com/okeefeco/pyeye-mcp.git
cd pyeye-mcp
pip install --user .

Configure with Claude Code (Global)

# Add the MCP server globally (available in all projects)
claude mcp add pyeye -s user -- python -m pyeye.mcp

# Verify it's connected
claude mcp list

Configure with Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "pyeye": {
      "command": "python",
      "args": ["-m", "pyeye.mcp"],
      "env": {}
    }
  }
}

Note: Use the full path to Python if needed (e.g., /usr/local/bin/python3 or C:\\Python311\\python.exe).

Configure with GitHub Copilot (VS Code)