Claude Code Integration
SwissArmyHammer integrates seamlessly with Claude Code through the Model Context Protocol (MCP). This guide shows you how to set up and use SwissArmyHammer with Claude Code.
What is MCP?
The Model Context Protocol allows AI assistants like Claude to access external tools and data sources. SwissArmyHammer acts as an MCP server, providing Claude Code with access to your prompt library.
Installation
1. Install SwissArmyHammer
See the Installation Guide for detailed instructions. The quickest method:
# Install using the install script
curl -sSL https://raw.githubusercontent.com/wballard/swissarmyhammer/main/install.sh | bash
2. Verify Installation
swissarmyhammer --version
3. Test the MCP Server
swissarmyhammer serve --help
Configuration
Add to Claude Code
Configure Claude Code to use SwissArmyHammer as an MCP server:
claude mcp add --scope user swissarmyhammer swissarmyhammer serve
This command:
- Adds
swissarmyhammer
as an MCP server name - Uses
swissarmyhammer serve
as the command to start the server - Sets user scope (available for your user account)
Alternative Configuration Methods
Manual Configuration
If you prefer to configure manually, add this to your Claude Code MCP configuration:
{
"mcpServers": {
"swissarmyhammer": {
"command": "swissarmyhammer",
"args": ["serve"]
}
}
}
Project-Specific Configuration
For project-specific prompts, create a local configuration:
# In your project directory
claude mcp add --scope project swissarmyhammer_local swissarmyhammer serve --prompts ./prompts
Verification
Check MCP Configuration
List your configured MCP servers:
claude mcp list
You should see swissarmyhammer
in the output.
Test the Connection
Start Claude Code and verify SwissArmyHammer is connected:
- Open Claude Code
- Look for SwissArmyHammer prompts in the available tools
- Try using a built-in prompt like
help
orplan
Debug Connection Issues
If SwissArmyHammer doesn’t appear in Claude Code:
# Check if the server starts correctly
swissarmyhammer serve --debug
# Verify prompts are loaded
swissarmyhammer list
# Check configuration
claude mcp list
Usage in Claude Code
Available Features
Once configured, SwissArmyHammer provides these features in Claude Code:
1. Prompt Library Access
All your prompts become available as tools in Claude Code:
- Built-in prompts (code review, debugging, documentation)
- User prompts (in
~/.swissarmyhammer/prompts/
) - Local prompts (in current project directory)
2. Dynamic Arguments
Prompts with arguments become interactive forms in Claude Code:
---
name: code-review
arguments:
- name: code
description: Code to review
required: true
- name: language
description: Programming language
required: false
default: auto-detect
---
3. Live Reloading
Changes to prompt files are automatically detected and reloaded.
Using Prompts
Basic Usage
- Select a Prompt: Choose from available SwissArmyHammer prompts
- Fill Arguments: Provide required and optional parameters
- Execute: Claude runs the prompt with your arguments
Example Workflow
-
Code Review:
- Select
code-review
prompt - Paste your code in the
code
field - Set
language
if needed - Execute to get detailed code analysis
- Select
-
Debug Helper:
- Select
debug
prompt - Describe your error in the
error
field - Get step-by-step debugging guidance
- Select
-
Documentation:
- Select
docs
prompt - Provide code or specifications
- Generate comprehensive documentation
- Select
Advanced Usage
Prompt Chaining
Use multiple prompts in sequence:
1. Use `analyze-code` to understand the codebase
2. Use `plan` to create implementation strategy
3. Use `code-review` on the new code
4. Use `docs` to generate documentation
Custom Workflows
Create project-specific prompt workflows:
# Project prompts in ./prompts/
## development/
- project-setup.md - Initialize new features
- code-standards.md - Apply project coding standards
- deployment.md - Deploy to staging/production
## documentation/
- api-docs.md - Generate API documentation
- user-guide.md - Create user-facing documentation
- changelog.md - Generate release notes
Configuration Options
Server Configuration
The swissarmyhammer serve
command accepts several options:
swissarmyhammer serve [OPTIONS]
Common Options
--port <PORT>
- Port for MCP communication (default: auto)--host <HOST>
- Host to bind to (default: localhost)--prompts <DIR>
- Additional prompt directories--builtin <BOOL>
- Include built-in prompts (default: true)--watch <BOOL>
- Enable file watching (default: true)--debug
- Enable debug logging
Examples
# Basic server
swissarmyhammer serve
# Custom prompt directory
swissarmyhammer serve --prompts /path/to/prompts
# Multiple prompt directories
swissarmyhammer serve --prompts ./prompts --prompts ~/.custom-prompts
# Debug mode
swissarmyhammer serve --debug
# Disable built-in prompts
swissarmyhammer serve --builtin false
Claude Code Configuration
Server Arguments
Pass arguments to the SwissArmyHammer server:
# Add with custom options
claude mcp add swissarmyhammer_custom swissarmyhammer serve --prompts ./project-prompts --debug
Environment Variables
Configure through environment variables:
export SWISSARMYHAMMER_PROMPTS_DIR=/path/to/prompts
export SWISSARMYHAMMER_DEBUG=true
claude mcp add swissarmyhammer swissarmyhammer serve
Prompt Organization
Directory Structure
Organize prompts for easy discovery in Claude Code:
~/.swissarmyhammer/prompts/
├── development/
│ ├── code-review.md
│ ├── debug-helper.md
│ ├── refactor.md
│ └── testing.md
├── writing/
│ ├── blog-post.md
│ ├── documentation.md
│ └── email.md
├── analysis/
│ ├── data-insights.md
│ └── research.md
└── productivity/
├── task-planning.md
└── meeting-notes.md
Naming Conventions
Use clear, descriptive names that work well in Claude Code:
# Good - Clear and specific
code-review-python.md
debug-javascript-async.md
documentation-api.md
# Bad - Too generic
review.md
debug.md
docs.md
Categories and Tags
Use categories and tags for better organization in Claude Code:
---
name: python-code-review
title: Python Code Review
description: Reviews Python code for PEP 8, security, and performance
category: development
tags: ["python", "code-review", "pep8", "security"]
---
Troubleshooting
Common Issues
SwissArmyHammer Not Available
Symptoms: SwissArmyHammer prompts don’t appear in Claude Code
Solutions:
- Verify installation:
swissarmyhammer --version
- Check MCP configuration:
claude mcp list
- Test server manually:
swissarmyhammer serve --debug
- Restart Claude Code
Connection Errors
Symptoms: Error messages about MCP connection
Solutions:
- Check if port is available:
swissarmyhammer serve --port 8080
- Verify permissions: Run with
--debug
to see detailed logs - Check firewall settings
- Try different host:
--host 127.0.0.1
Prompts Not Loading
Symptoms: Some prompts missing or outdated
Solutions:
- Check prompt syntax:
swissarmyhammer test <prompt-name>
- Verify file permissions in prompt directories
- Check for YAML syntax errors
- Restart the MCP server: Restart Claude Code
Performance Issues
Symptoms: Slow prompt loading or execution
Solutions:
- Reduce prompt directory size
- Disable file watching:
--watch false
- Use specific prompt directories:
--prompts ./specific-dir
- Check system resources
Debug Mode
Enable debug mode for detailed troubleshooting:
swissarmyhammer serve --debug
Debug mode provides:
- Detailed logging of MCP communication
- Prompt loading information
- Error stack traces
- Performance metrics
Logs and Diagnostics
Server Logs
SwissArmyHammer logs to standard output:
# Save logs to file
swissarmyhammer serve --debug > swissarmyhammer.log 2>&1
Claude Code Logs
Check Claude Code logs for MCP-related issues:
# Location varies by platform
# macOS: ~/Library/Logs/Claude Code/
# Linux: ~/.local/share/claude-code/logs/
# Windows: %APPDATA%/Claude Code/logs/
Health Check
Use the doctor command to check configuration:
swissarmyhammer doctor
This checks:
- Installation status
- Configuration validity
- Prompt directory accessibility
- MCP server functionality
Best Practices
1. Organize Prompts Logically
Structure prompts by workflow rather than just topic:
prompts/
├── workflows/
│ ├── code-review-workflow.md
│ ├── feature-development.md
│ └── bug-fixing.md
├── utilities/
│ ├── format-code.md
│ ├── generate-tests.md
│ └── extract-docs.md
2. Use Descriptive Metadata
Make prompts discoverable with good metadata:
---
name: comprehensive-code-review
title: Comprehensive Code Review
description: Deep analysis of code for security, performance, and maintainability
category: development
tags: ["security", "performance", "maintainability", "best-practices"]
keywords: ["static analysis", "code quality", "peer review"]
---
3. Test Prompts Regularly
Validate prompts before using in Claude Code:
# Test basic functionality
swissarmyhammer test code-review --code "def hello(): print('hi')"
# Test all prompts
swissarmyhammer test --all
4. Use Project-Specific Configurations
Create project-specific prompt collections:
# Per-project MCP server
cd my-project
claude mcp add project_prompts swissarmyhammer serve --prompts ./prompts
5. Keep Prompts Updated
Maintain prompt quality:
---
name: my-prompt
version: 1.2.0
updated: 2024-03-20 # Track changes
---
Examples
Complete Setup Example
Here’s a complete example of setting up SwissArmyHammer for a development project:
# 1. Install SwissArmyHammer
curl -sSL https://raw.githubusercontent.com/wballard/swissarmyhammer/main/install.sh | bash
# 2. Create project prompts
mkdir -p ./prompts/development
cat > ./prompts/development/project-review.md << 'EOF'
---
name: project-code-review
title: Project Code Review
description: Reviews code according to our project standards
category: development
arguments:
- name: code
description: Code to review
required: true
- name: component
description: Which component this code belongs to
required: false
default: general
---
# Project Code Review
Please review this {{component}} code according to our project standards:
```{{code}}```
Check for:
- Adherence to our coding standards
- Security best practices
- Performance considerations
- Documentation completeness
- Test coverage
Provide specific, actionable feedback.
EOF
# 3. Configure Claude Code
claude mcp add project_sah swissarmyhammer serve --prompts ./prompts
# 4. Test the setup
swissarmyhammer test project-code-review --code "print('hello')" --component "utility"
# 5. Start using in Claude Code
echo "Setup complete! Restart Claude Code to use your prompts."
Next Steps
- Explore Built-in Prompts to see what’s available
- Learn Creating Prompts to build custom prompts
- Read about Prompt Organization strategies
- Check the CLI Reference for all available commands
- See Troubleshooting for additional help