{
  "markdown": "# Periphery MCP Server\n\nA [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that wraps the [Periphery](https://github.com/peripheryapp/periphery) tool, enabling AI assistants to perform Swift code audits and detect unused code in iOS/macOS projects.\n\n## Features\n\n- **7 MCP Tools** for comprehensive code analysis\n- **CLI Integration** - Uses Periphery CLI for stability and version flexibility\n- **JSON Output** - Structured, parseable results perfect for AI interpretation\n- **Flexible Scanning** - Support for Xcode projects and Swift Packages\n- **Advanced Options** - Full control over Periphery scan configurations\n\n## Quick Start\n\n**Using Homebrew (Recommended):**\n\n```bash\n# 1. Install Periphery\nbrew install peripheryapp/periphery/periphery\n\n# 2. Install Periphery MCP Server\nbrew tap zyntx-lab/tap\nbrew install periphery-mcp-server\n\n# 3. Configure Claude Desktop\n# Edit: ~/Library/Application Support/Claude/claude_desktop_config.json\n# Add:\n#   \"periphery\": {\n#     \"command\": \"/opt/homebrew/bin/periphery-mcp-server\"\n#   }\n\n# 4. Restart Claude Desktop (Cmd+Q then reopen)\n\n# 5. Test it\n# In Claude Desktop: \"Check if Periphery is installed\"\n```\n\n**From Source:**\n\n```bash\n# 1. Install Periphery\nbrew install peripheryapp/periphery/periphery\n\n# 2. Clone and build this server\ngit clone https://github.com/zyntx-lab/periphery-mcp-server.git\ncd periphery-mcp-server\nswift build -c release\n\n# 3. Install to system path\nsudo cp .build/release/periphery-mcp-server /usr/local/bin/\nsudo chmod +x /usr/local/bin/periphery-mcp-server\n\n# 4. Configure Claude Desktop\n# Edit: ~/Library/Application Support/Claude/claude_desktop_config.json\n# Add:\n#   \"periphery\": {\n#     \"command\": \"/usr/local/bin/periphery-mcp-server\"\n#   }\n\n# 5. Restart Claude Desktop (Cmd+Q then reopen)\n\n# 6. Test it\n# In Claude Desktop: \"Check if Periphery is installed\"\n```\n\n## Prerequisites\n\n- macOS 13.0 or later\n- Swift 6.0 or later\n- [Periphery](https://github.com/peripheryapp/periphery) installed\n\n### Installing Periphery\n\n```bash\nbrew install peripheryapp/periphery/periphery\n```\n\nOr download from [Periphery releases](https://github.com/peripheryapp/periphery/releases).\n\n## Installation\n\n### Option 1: Homebrew (Recommended)\n\n```bash\n# Add the tap\nbrew tap zyntx-lab/tap\n\n# Install the server\nbrew install periphery-mcp-server\n\n# Verify installation\nwhich periphery-mcp-server\n# Should output: /opt/homebrew/bin/periphery-mcp-server\n```\n\n### Option 2: Download from GitHub Releases\n\nDownload the latest binary from [Releases](https://github.com/zyntx-lab/periphery-mcp-server/releases):\n\n```bash\n# Download and install\ncurl -L https://github.com/zyntx-lab/periphery-mcp-server/releases/download/v1.0.0/periphery-mcp-server \\\n  -o /usr/local/bin/periphery-mcp-server\nchmod +x /usr/local/bin/periphery-mcp-server\n\n# Verify installation\nwhich periphery-mcp-server\n# Should output: /usr/local/bin/periphery-mcp-server\n```\n\n### Option 3: Build from Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/zyntx-lab/periphery-mcp-server.git\ncd periphery-mcp-server\n\n# Build release version\nswift build -c release\n\n# Install to system path (requires password)\nsudo cp .build/release/periphery-mcp-server /usr/local/bin/\nsudo chmod +x /usr/local/bin/periphery-mcp-server\n\n# Verify installation\nwhich periphery-mcp-server\n# Should output: /usr/local/bin/periphery-mcp-server\n```\n\n### Option 4: Install from MCP Registry\n\nThe server is also available on the [MCP Registry](https://registry.modelcontextprotocol.io). Use your MCP-compatible client to install it directly.\n\n## Configuration\n\n### Claude Desktop\n\n#### Step 1: Locate Your Config File\n\nThe config file is at: `~/Library/Application Support/Claude/claude_desktop_config.json`\n\n#### Step 2: Edit the Configuration\n\n**If you installed via Homebrew:**\n\n```json\n{\n  \"mcpServers\": {\n    \"periphery\": {\n      \"command\": \"/opt/homebrew/bin/periphery-mcp-server\"\n    }\n  }\n}\n```\n\n**If you installed to /usr/local/bin:**\n\n```json\n{\n  \"mcpServers\": {\n    \"periphery\": {\n      \"command\": \"/usr/local/bin/periphery-mcp-server\"\n    }\n  }\n}\n```\n\n**If you're using the build directory directly:**\n\n```json\n{\n  \"mcpServers\": {\n    \"periphery\": {\n      \"command\": \"/FULL/PATH/TO/periphery-mcp-server/.build/release/periphery-mcp-server\"\n    }\n  }\n}\n```\n\n**If you already have other MCP servers configured:**\n\n```json\n{\n  \"mcpServers\": {\n    \"xcode\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/xcode-mcp-server/dist/index.js\"]\n    },\n    \"periphery\": {\n      \"command\": \"/usr/local/bin/periphery-mcp-server\"\n    }\n  }\n}\n```\n\n#### Step 3: Restart Claude Desktop\n\n**Important:** You must completely quit and restart Claude Desktop for changes to take effect.\n\n1. Quit Claude Desktop: Press `Cmd+Q` or use Claude Desktop → Quit\n2. Wait a few seconds\n3. Reopen Claude Desktop\n\n#### Step 4: Verify It's Working\n\nOpen a new conversation in Claude Desktop and try:\n\n```\n\"Check if Periphery is installed\"\n```\n\nIf configured correctly, Claude will use the `check_periphery_installed` tool and respond with installation status.\n\n### Testing with MCP Inspector\n\nBefore configuring Claude Desktop, you can test the server with the MCP Inspector:\n\n```bash\n# Install MCP Inspector (if not already installed)\nnpm install -g @modelcontextprotocol/inspector\n\n# Test your server\nnpx @modelcontextprotocol/inspector /usr/local/bin/periphery-mcp-server\n\n# Or if using build directory\nnpx @modelcontextprotocol/inspector /path/to/periphery-mcp-server/.build/release/periphery-mcp-server\n```\n\nThe Inspector will open in your browser where you can test all tools interactively.\n\n### Other Editors\n\n#### VS Code\n\nAdd to `.vscode/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"periphery\": {\n      \"type\": \"stdio\",\n      \"command\": \"/usr/local/bin/periphery-mcp-server\"\n    }\n  }\n}\n```\n\n#### Cursor\n\nAdd to `.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"periphery\": {\n      \"type\": \"stdio\",\n      \"command\": \"/usr/local/bin/periphery-mcp-server\"\n    }\n  }\n}\n```\n\n## Available Tools\n\n### 1. `check_periphery_installed`\n\nVerify that Periphery CLI is installed and accessible.\n\n**Parameters:** None\n\n**Example Response:**\n```json\n{\n  \"installed\": true,\n  \"path\": \"/usr/local/bin/periphery\",\n  \"message\": \"Periphery is installed and ready\"\n}\n```\n\n### 2. `get_periphery_version`\n\nGet the installed version of Periphery.\n\n**Parameters:** None\n\n**Example Response:**\n```json\n{\n  \"version\": \"2.18.0\",\n  \"raw_output\": \"2.18.0\"\n}\n```\n\n### 3. `scan_project`\n\nRun a basic Periphery scan on a project.\n\n**Parameters:**\n- `project_path` (required): Path to .xcodeproj or Package.swift\n- `schemes` (optional): Build schemes to scan (Xcode only)\n- `targets` (optional): Specific targets to analyze\n- `format` (optional): Output format: json, xcode, csv, checkstyle (default: json)\n\n**Example Response:**\n```json\n{\n  \"success\": true,\n  \"results\": [\n    {\n      \"kind\": \"class\",\n      \"name\": \"UnusedClass\",\n      \"modifiers\": [\"public\"],\n      \"location\": \"Sources/MyApp/UnusedClass.swift:10:7\"\n    }\n  ],\n  \"summary\": {\n    \"total_unused\": 5,\n    \"by_kind\": {\"class\": 2, \"function\": 3}\n  }\n}\n```\n\n### 4. `scan_with_config`\n\nRun Periphery scan using a YAML configuration file.\n\n**Parameters:**\n- `config_path` (required): Path to .periphery.yml config file\n\n### 5. `analyze_unused_imports`\n\nFocus specifically on detecting unused imports.\n\n**Parameters:**\n- `project_path` (required): Path to .xcodeproj or Package.swift\n- `schemes` (optional): Build schemes to scan\n- `targets` (optional): Specific targets to analyze\n\n### 6. `find_redundant_public`\n\nIdentify public declarations that could be internal.\n\n**Parameters:**\n- `project_path` (required): Path to .xcodeproj or Package.swift\n- `schemes` (optional): Build schemes to scan\n- `targets` (optional): Specific targets to analyze\n\n### 7. `scan_with_options`\n\nAdvanced scanning with custom Periphery flags.\n\n**Parameters:**\n- `project_path` (required): Path to .xcodeproj or Package.swift\n- `schemes` (optional): Build schemes to scan\n- `targets` (optional): Specific targets to analyze\n- `format` (optional): Output format\n- `retain_public` (optional): Retain all public declarations\n- `retain_objc_accessible` (optional): Retain @objc declarations\n- `disable_unused_import_analysis` (optional): Disable unused import analysis\n- `index_store_path` (optional): Custom index store location\n- `verbose` (optional): Enable verbose output\n\n## Usage Examples\n\n### With Claude Desktop\n\nOnce configured, you can have natural conversations with Claude about your code:\n\n**Check Installation:**\n```\nYou: \"Check if Periphery is installed\"\n\nClaude: [Uses check_periphery_installed]\n\"Yes, Periphery is installed at /usr/local/bin/periphery\nVersion: 2.18.0\"\n```\n\n**Scan a Project:**\n```\nYou: \"Scan my iOS project at ~/Projects/MyApp/MyApp.xcodeproj for unused code\"\n\nClaude: [Uses scan_project]\n\"I found 15 unused declarations in your project:\n\nClasses (5):\n- UnusedViewController at MyApp/UnusedViewController.swift:10\n- OldDataManager at MyApp/Models/OldDataManager.swift:25\n...\n\nFunctions (8):\n- helperFunction at Utils/Helpers.swift:42\n...\n\nImports (2):\n- UIKit in DataModel.swift:1\n...\"\n```\n\n**Find Redundant Public:**\n```\nYou: \"Check which public declarations could be made internal in ~/Projects/MyFramework\"\n\nClaude: [Uses find_redundant_public]\n\"Found 12 public declarations that are only used internally and could be made internal:\n- public class InternalHelper (only used within the framework)\n- public func formatDate() (only called from within the module)\n...\"\n```\n\n**Analyze Unused Imports:**\n```\nYou: \"Find unused imports in my Swift package\"\n\nClaude: [Uses analyze_unused_imports]\n\"Found 8 unused imports that can be safely removed:\n- Foundation in Models/User.swift (not using any Foundation APIs)\n- Combine in ViewModels/ProfileViewModel.swift (Combine is imported but not used)\n...\"\n```\n\n### With Custom Configuration\n\nCreate `.periphery.yml` in your project:\n\n```yaml\nproject: MyApp.xcodeproj\nschemes:\n  - MyApp\ntargets:\n  - MyApp\n  - MyAppKit\nformat: json\nretain_public: false\nretain_objc_accessible: true\nverbose: false\n```\n\nThen use `scan_with_config`:\n\n```\nYou: \"Scan my project using the custom config\"\n```\n\n## Troubleshooting\n\n### Server Not Appearing in Claude Desktop\n\n**Symptoms:** Claude doesn't recognize Periphery tools after configuration\n\n**Solutions:**\n\n1. **Verify config file syntax:**\n   ```bash\n   # Check for JSON syntax errors\n   cat ~/Library/Application\\ Support/Claude/claude_desktop_config.json | python3 -m json.tool\n   ```\n\n2. **Check the binary path is correct:**\n   ```bash\n   # Test that the binary exists and runs\n   /usr/local/bin/periphery-mcp-server\n   # Or your custom path\n   /path/to/.build/release/periphery-mcp-server\n   ```\n\n3. **Completely restart Claude Desktop:**\n   - Press `Cmd+Q` to quit (not just close the window)\n   - Wait 5 seconds\n   - Reopen Claude Desktop\n   - Start a new conversation (old conversations won't see new servers)\n\n4. **Check Claude Desktop logs:**\n   ```bash\n   # View logs for errors\n   tail -f ~/Library/Logs/Claude/mcp*.log\n   ```\n\n### Periphery Not Found\n\nIf you get \"Periphery is not installed\":\n\n1. Install Periphery: `brew install peripheryapp/periphery/periphery`\n2. Verify installation: `which periphery`\n3. Restart Claude Desktop/VS Code/Cursor\n4. Try the `check_periphery_installed` tool again\n\n### MCP Inspector Connection Errors\n\nIf the Inspector can't connect to the server:\n\n1. **Verify the server runs:**\n   ```bash\n   # Server should wait for input, not exit immediately\n   /usr/local/bin/periphery-mcp-server\n   # Press Ctrl+C to exit\n   ```\n\n2. **Check for errors:**\n   ```bash\n   # Run with verbose output\n   /usr/local/bin/periphery-mcp-server 2>&1 | tee server.log\n   ```\n\n3. **Use the absolute path:**\n   ```bash\n   npx @modelcontextprotocol/inspector $(which periphery-mcp-server)\n   ```\n\n### Scan Timeout\n\nDefault timeout is 5 minutes. For large projects:\n\n1. Use `scan_with_config` with a focused configuration\n2. Scan specific targets instead of the entire project\n3. Use `--index-store-path` to reuse build artifacts\n4. Build your project in Xcode first to generate the index\n\n### No Results or Empty Scan\n\nPeriphery requires a compiled project with an index store:\n\n1. **Build your project first in Xcode** (Cmd+B)\n2. **Ensure schemes are shared:**\n   - Xcode → Product → Scheme → Manage Schemes\n   - Check the \"Shared\" checkbox for your scheme\n3. **Verify the project path:**\n   ```bash\n   # For Xcode projects\n   ls /path/to/YourProject.xcodeproj\n\n   # For Swift Packages\n   ls /path/to/Package.swift\n   ```\n4. **Check Periphery can access the project:**\n   ```bash\n   # Test Periphery directly\n   periphery scan --project /path/to/YourProject.xcodeproj --schemes YourScheme\n   ```\n\n### Permission Denied\n\nIf you get \"Permission denied\" when running the server:\n\n```bash\n# Make the binary executable\nchmod +x /usr/local/bin/periphery-mcp-server\n\n# Or for build directory\nchmod +x .build/release/periphery-mcp-server\n```\n\n## Architecture\n\nThis server uses the **CLI approach** rather than importing Periphery as a library for maximum stability:\n\n- ✅ CLI interface is Periphery's public API contract\n- ✅ Survives internal Periphery refactorings\n- ✅ Users can update Periphery independently\n- ✅ Simpler dependency management\n\n## Contributing\n\nContributions are welcome! Please:\n\n1. Fork the repository\n2. Create a feature branch\n3. Add tests for new functionality\n4. Submit a pull request\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## Related Projects\n\n- [Periphery](https://github.com/peripheryapp/periphery) - The underlying code analysis tool\n- [Model Context Protocol](https://modelcontextprotocol.io) - The protocol specification\n- [MCP Swift SDK](https://github.com/modelcontextprotocol/swift-sdk) - Official Swift SDK for MCP\n- [MCP Registry](https://registry.modelcontextprotocol.io) - Official MCP server registry\n- [MCP Community Servers](https://github.com/modelcontextprotocol/servers) - Collection of community MCP servers\n\n## Distribution Channels\n\nThis server is available through multiple channels:\n\n- **MCP Registry**: [registry.modelcontextprotocol.io](https://registry.modelcontextprotocol.io)\n- **Homebrew Tap**: [github.com/zyntx-lab/homebrew-tap](https://github.com/zyntx-lab/homebrew-tap)\n- **GitHub Releases**: [github.com/zyntx-lab/periphery-mcp-server/releases](https://github.com/zyntx-lab/periphery-mcp-server/releases)\n- **Community Servers**: Listed in [modelcontextprotocol/servers](https://github.com/modelcontextprotocol/servers)\n\n## Support\n\n- **Issues**: [GitHub Issues](https://github.com/zyntx-lab/periphery-mcp-server/issues)\n- **Periphery Docs**: [Periphery Guide](https://github.com/peripheryapp/periphery)\n- **MCP Docs**: [MCP Specification](https://spec.modelcontextprotocol.io)\n",
  "bytes": 14825,
  "sha": "9ee17bf05b77e9072e3721fc44b5f5c61f1cd5cccf680cee51aebd42ae0f6f32",
  "repo_slug": "zyntx-lab/periphery-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_zyntx_lab_periphery_mcp_server_ef9e5561/readme"
}