Periphery Code Audit

Periphery MCP Server

A Model Context Protocol (MCP) server that wraps the Periphery tool, enabling AI assistants to perform Swift code audits and detect unused code in iOS/macOS projects.

Features

• 7 MCP Tools for comprehensive code analysis
• CLI Integration - Uses Periphery CLI for stability and version flexibility
• JSON Output - Structured, parseable results perfect for AI interpretation
• Flexible Scanning - Support for Xcode projects and Swift Packages
• Advanced Options - Full control over Periphery scan configurations

Quick Start

Using Homebrew (Recommended):

# 1. Install Peripherybrew install peripheryapp/periphery/periphery
# 2. Install Periphery MCP Serverbrew tap zyntx-lab/tapbrew install periphery-mcp-server
# 3. Configure Claude Desktop# Edit: ~/Library/Application Support/Claude/claude_desktop_config.json# Add:#   "periphery": {#     "command": "/opt/homebrew/bin/periphery-mcp-server"#   }
# 4. Restart Claude Desktop (Cmd+Q then reopen)
# 5. Test it# In Claude Desktop: "Check if Periphery is installed"

From Source:

# 1. Install Peripherybrew install peripheryapp/periphery/periphery
# 2. Clone and build this servergit clone https://github.com/zyntx-lab/periphery-mcp-server.gitcd periphery-mcp-serverswift build -c release
# 3. Install to system pathsudo cp .build/release/periphery-mcp-server /usr/local/bin/sudo chmod +x /usr/local/bin/periphery-mcp-server
# 4. Configure Claude Desktop# Edit: ~/Library/Application Support/Claude/claude_desktop_config.json# Add:#   "periphery": {#     "command": "/usr/local/bin/periphery-mcp-server"#   }
# 5. Restart Claude Desktop (Cmd+Q then reopen)
# 6. Test it# In Claude Desktop: "Check if Periphery is installed"

Prerequisites

• macOS 13.0 or later
• Swift 6.0 or later
• Periphery installed

Installing Periphery

brew install peripheryapp/periphery/periphery

Or download from Periphery releases.

Installation

Option 1: Homebrew (Recommended)

# Add the tapbrew tap zyntx-lab/tap
# Install the serverbrew install periphery-mcp-server
# Verify installationwhich periphery-mcp-server# Should output: /opt/homebrew/bin/periphery-mcp-server

Option 2: Download from GitHub Releases

Download the latest binary from Releases:

# Download and installcurl -L https://github.com/zyntx-lab/periphery-mcp-server/releases/download/v1.0.0/periphery-mcp-server \  -o /usr/local/bin/periphery-mcp-serverchmod +x /usr/local/bin/periphery-mcp-server
# Verify installationwhich periphery-mcp-server# Should output: /usr/local/bin/periphery-mcp-server

Option 3: Build from Source

# Clone the repositorygit clone https://github.com/zyntx-lab/periphery-mcp-server.gitcd periphery-mcp-server
# Build release versionswift build -c release
# Install to system path (requires password)sudo cp .build/release/periphery-mcp-server /usr/local/bin/sudo chmod +x /usr/local/bin/periphery-mcp-server
# Verify installationwhich periphery-mcp-server# Should output: /usr/local/bin/periphery-mcp-server

Option 4: Install from MCP Registry

The server is also available on the MCP Registry. Use your MCP-compatible client to install it directly.

Configuration

Claude Desktop

Step 1: Locate Your Config File

The config file is at: ~/Library/Application Support/Claude/claude_desktop_config.json

Step 2: Edit the Configuration

If you installed via Homebrew:

{  "mcpServers": {    "periphery": {      "command": "/opt/homebrew/bin/periphery-mcp-server"    }  }}

If you installed to /usr/local/bin:

{  "mcpServers": {    "periphery": {      "command": "/usr/local/bin/periphery-mcp-server"    }  }}

If you're using the build directory directly:

{  "mcpServers": {    "periphery": {      "command": "/FULL/PATH/TO/periphery-mcp-server/.build/release/periphery-mcp-server"    }  }}

If you already have other MCP servers configured:

{  "mcpServers": {    "xcode": {      "command": "node",      "args": ["/path/to/xcode-mcp-server/dist/index.js"]    },    "periphery": {      "command": "/usr/local/bin/periphery-mcp-server"    }  }}

Step 3: Restart Claude Desktop

Important: You must completely quit and restart Claude Desktop for changes to take effect.

1. Quit Claude Desktop: Press Cmd+Q or use Claude Desktop → Quit
2. Wait a few seconds
3. Reopen Claude Desktop

Step 4: Verify It's Working

Open a new conversation in Claude Desktop and try:

"Check if Periphery is installed"

If configured correctly, Claude will use the check_periphery_installed tool and respond with installation status.

Testing with MCP Inspector

Before configuring Claude Desktop, you can test the server with the MCP Inspector:

# Install MCP Inspector (if not already installed)npm install -g @modelcontextprotocol/inspector
# Test your servernpx @modelcontextprotocol/inspector /usr/local/bin/periphery-mcp-server
# Or if using build directorynpx @modelcontextprotocol/inspector /path/to/periphery-mcp-server/.build/release/periphery-mcp-server

The Inspector will open in your browser where you can test all tools interactively.

Other Editors

VS Code

Add to .vscode/mcp.json:

{  "mcpServers": {    "periphery": {      "type": "stdio",      "command": "/usr/local/bin/periphery-mcp-server"    }  }}

Cursor

Add to .cursor/mcp.json:

{  "mcpServers": {    "periphery": {      "type": "stdio",      "command": "/usr/local/bin/periphery-mcp-server"    }  }}

Available Tools

1. check_periphery_installed

Verify that Periphery CLI is installed and accessible.

Parameters: None

Example Response:

{  "installed": true,  "path": "/usr/local/bin/periphery",  "message": "Periphery is installed and ready"}

2. get_periphery_version

Get the installed version of Periphery.

Parameters: None

Example Response:

{  "version": "2.18.0",  "raw_output": "2.18.0"}

3. scan_project

Run a basic Periphery scan on a project.

Parameters:

• project_path (required): Path to .xcodeproj or Package.swift
• schemes (optional): Build schemes to scan (Xcode only)
• targets (optional): Specific targets to analyze
• format (optional): Output format: json, xcode, csv, checkstyle (default: json)

Example Response:

{  "success": true,  "results": [    {      "kind": "class",      "name": "UnusedClass",      "modifiers": ["public"],      "location": "Sources/MyApp/UnusedClass.swift:10:7"    }  ],  "summary": {    "total_unused": 5,    "by_kind": {"class": 2, "function": 3}  }}

4. scan_with_config

Run Periphery scan using a YAML configuration file.

Parameters:

• config_path (required): Path to .periphery.yml config file

5. analyze_unused_imports

Focus specifically on detecting unused imports.

Parameters:

• project_path (required): Path to .xcodeproj or Package.swift
• schemes (optional): Build schemes to scan
• targets (optional): Specific targets to analyze

6. find_redundant_public

Identify public declarations that could be internal.

Parameters:

• project_path (required): Path to .xcodeproj or Package.swift
• schemes (optional): Build schemes to scan
• targets (optional): Specific targets to analyze

7. scan_with_options

Advanced scanning with custom Periphery flags.

Parameters:

• project_path (required): Path to .xcodeproj or Package.swift
• schemes (optional): Build schemes to scan
• targets (optional): Specific targets to analyze
• format (optional): Output format
• retain_public (optional): Retain all public declarations
• retain_objc_accessible (optional): Retain @objc declarations
• disable_unused_import_analysis (optional): Disable unused import analysis
• index_store_path (optional): Custom index store location
• verbose (optional): Enable verbose output

Usage Examples

With Claude Desktop

Once configured, you can have natural conversations with Claude about your code:

Check Installation:

You: "Check if Periphery is installed"
Claude: [Uses check_periphery_installed]"Yes, Periphery is installed at /usr/local/bin/peripheryVersion: 2.18.0"

Scan a Project:

You: "Scan my iOS project at ~/Projects/MyApp/MyApp.xcodeproj for unused code"
Claude: [Uses scan_project]"I found 15 unused declarations in your project:
Classes (5):- UnusedViewController at MyApp/UnusedViewController.swift:10- OldDataManager at MyApp/Models/OldDataManager.swift:25...
Functions (8):- helperFunction at Utils/Helpers.swift:42...
Imports (2):- UIKit in DataModel.swift:1..."

Find Redundant Public:

You: "Check which public declarations could be made internal in ~/Projects/MyFramework"
Claude: [Uses find_redundant_public]"Found 12 public declarations that are only used internally and could be made internal:- public class InternalHelper (only used within the framework)- public func formatDate() (only called from within the module)..."

Analyze Unused Imports:

You: "Find unused imports in my Swift package"
Claude: [Uses analyze_unused_imports]"Found 8 unused imports that can be safely removed:- Foundation in Models/User.swift (not using any Foundation APIs)- Combine in ViewModels/ProfileViewModel.swift (Combine is imported but not used)..."

With Custom Configuration

Create .periphery.yml in your project:

project: MyApp.xcodeprojschemes:  - MyApptargets:  - MyApp  - MyAppKitformat: jsonretain_public: falseretain_objc_accessible: trueverbose: false

Then use scan_with_config:

You: "Scan my project using the custom config"

Troubleshooting

Server Not Appearing in Claude Desktop

Symptoms: Claude doesn't recognize Periphery tools after configuration

Solutions:

1. Verify config file syntax:

   bash

   # Check for JSON syntax errorscat ~/Library/Application\ Support/Claude/claude_desktop_config.json | python3 -m json.tool

2. Check the binary path is correct:

   bash

   # Test that the binary exists and runs/usr/local/bin/periphery-mcp-server# Or your custom path/path/to/.build/release/periphery-mcp-server

3. Completely restart Claude Desktop:

   • Press Cmd+Q to quit (not just close the window)
   • Wait 5 seconds
   • Reopen Claude Desktop
   • Start a new conversation (old conversations won't see new servers)

4. Check Claude Desktop logs:

   bash

   # View logs for errorstail -f ~/Library/Logs/Claude/mcp*.log

Periphery Not Found

If you get "Periphery is not installed":

1. Install Periphery: brew install peripheryapp/periphery/periphery
2. Verify installation: which periphery
3. Restart Claude Desktop/VS Code/Cursor
4. Try the check_periphery_installed tool again

MCP Inspector Connection Errors

If the Inspector can't connect to the server:

1. Verify the server runs:

   bash

   # Server should wait for input, not exit immediately/usr/local/bin/periphery-mcp-server# Press Ctrl+C to exit

2. Check for errors:

   bash

   # Run with verbose output/usr/local/bin/periphery-mcp-server 2>&1 | tee server.log

3. Use the absolute path:

   bash

   npx @modelcontextprotocol/inspector $(which periphery-mcp-server)

Scan Timeout

Default timeout is 5 minutes. For large projects:

1. Use scan_with_config with a focused configuration
2. Scan specific targets instead of the entire project
3. Use --index-store-path to reuse build artifacts
4. Build your project in Xcode first to generate the index

No Results or Empty Scan

Periphery requires a compiled project with an index store:

1. Build your project first in Xcode (Cmd+B)
2. Ensure schemes are shared:
   • Xcode → Product → Scheme → Manage Schemes
   • Check the "Shared" checkbox for your scheme
3. Verify the project path:
   bash

   # For Xcode projectsls /path/to/YourProject.xcodeproj
   # For Swift Packagesls /path/to/Package.swift

4. Check Periphery can access the project:
   bash

   # Test Periphery directlyperiphery scan --project /path/to/YourProject.xcodeproj --schemes YourScheme

Permission Denied

If you get "Permission denied" when running the server:

# Make the binary executablechmod +x /usr/local/bin/periphery-mcp-server
# Or for build directorychmod +x .build/release/periphery-mcp-server

Architecture

This server uses the CLI approach rather than importing Periphery as a library for maximum stability:

• ✅ CLI interface is Periphery's public API contract
• ✅ Survives internal Periphery refactorings
• ✅ Users can update Periphery independently
• ✅ Simpler dependency management

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Submit a pull request

License

MIT License - see LICENSE file for details.

Related Projects

• Periphery - The underlying code analysis tool
• Model Context Protocol - The protocol specification
• MCP Swift SDK - Official Swift SDK for MCP
• MCP Registry - Official MCP server registry
• MCP Community Servers - Collection of community MCP servers

Distribution Channels

This server is available through multiple channels:

• MCP Registry: registry.modelcontextprotocol.io
• Homebrew Tap: github.com/zyntx-lab/homebrew-tap
• GitHub Releases: github.com/zyntx-lab/periphery-mcp-server/releases
• Community Servers: Listed in modelcontextprotocol/servers

Support

• Issues: GitHub Issues
• Periphery Docs: Periphery Guide
• MCP Docs: MCP Specification