MCP server for Klipper 3D printer firmware documentation
npm install mcp-klipper-docsbash
Install globally
npm install -g mcp-klipper-docs
Or install locally in your project
npm install mcp-klipper-docs
`
$3
1. Open your Claude Desktop config file:
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
2. Add the MCP server:
#### Option 1: Global Installation (Recommended)
`json
{
"mcpServers": {
"klipper-docs": {
"command": "node",
"args": ["C:\\Users\\bpuhnk\\AppData\\Roaming\\npm\\node_modules\\mcp-klipper-docs\\dist\\server.js"]
}
}
}
`
#### Option 2: Using npx
`json
{
"mcpServers": {
"klipper-docs": {
"command": "npx",
"args": ["-y", "mcp-klipper-docs@1.0.1"]
}
}
}
`
#### Option 3: Local Development
`json
{
"mcpServers": {
"klipper-docs": {
"command": "node",
"args": ["C:\\Users\\bpuhnk\\source\\repos\\MCP_Klipper\\dist\\server.js"]
}
}
}
`
3. Restart Claude Desktop
That's it! 🎉 Claude now has instant access to all Klipper documentation.
$3
- npm Package: mcp-klipper-docs
- Version: 1.0.1
- Repository: GitHub
- License: MIT
- Author: Ben Phillips
$3
After installation, verify everything works:
`bash
Check package installation
npm list -g mcp-klipper-docs
Test server startup
node C:\Users\bpuhnk\AppData\Roaming\npm\node_modules\mcp-klipper-docs\dist\server.js
Or using npx
npx -y mcp-klipper-docs@1.0.1
`
---
🛠️ What Can You Do?
$3
`
"Search for BLTouch configuration"
"Find information about pressure advance"
"Look up extruder tuning guides"
`
$3
`
"Get configuration for [extruder]"
"Show me stepper_x settings"
"What are the bed_mesh parameters?"
`
$3
`
"Browse calibration documentation"
"Show me hardware configuration sections"
"What's in the troubleshooting section?"
`
$3
`
"How many documents are available?"
"What sections exist in the documentation?"
"Show me index statistics"
`
---
🏗️ Architecture
$3
`mermaid
graph TD
A[Claude Desktop] --> B[MCP Protocol]
B --> C[MCP Server]
C --> D[Search Engine]
C --> E[Document Parser]
C --> F[Git Sync]
D --> G[Lunr.js Index]
E --> H[Markdown Files]
F --> I[Klipper Repository]
`
$3
| Component | Technology | Purpose |
|-----------|------------|---------|
| Runtime | Node.js 20+ | JavaScript execution |
| Language | TypeScript 5.3+ | Type safety & development |
| Protocol | MCP SDK 1.0+ | Claude Desktop integration |
| Search | Lunr.js 2.3+ | Full-text search indexing |
| Git | simple-git 3.22+ | Repository synchronization |
| Parsing | marked 11.1+ | Markdown processing |
| Metadata | gray-matter 4.0+ | Frontmatter extraction |
$3
1. Repository Sync: Automatically pulls latest Klipper documentation
2. Document Parsing: Extracts content, metadata, and structure
3. Index Building: Creates searchable lunr.js index
4. MCP Integration: Exposes tools and resources via MCP protocol
5. AI Interaction: Claude searches and retrieves documentation
---
📋 Available Tools
$3
Search across all Klipper documentation with relevance scoring.
Parameters:
- query (string): Search terms
- limit (number, optional): Max results (default: 10)
- section (string, optional): Filter by section
Example:
`json
{
"query": "BLTouch configuration",
"limit": 5,
"section": "hardware"
}
`
$3
Retrieve specific configuration sections from Config_Reference.
Parameters:
- option (string): Configuration option name
- include_examples (boolean, optional): Include code examples
Example:
`json
{
"option": "extruder",
"include_examples": true
}
`
$3
Browse documentation by section or get overview information.
Parameters:
- section (string, optional): Section to browse
- include_stats (boolean, optional): Include statistics
Example:
`json
{
"section": "calibration",
"include_stats": true
}
`
$3
Get documentation index statistics and metadata.
No parameters required.
---
📁 MCP Resources
All documentation files are available as MCP resources:
- URI Scheme: klipper://docs/{document-id}
- Format: Markdown with metadata
- Access: Direct file reading or browsing
Example Resources:
- klipper://docs/Config_Reference
- klipper://docs/BLTouch
- klipper://docs/Installation
- klipper://docs/Troubleshooting
---
🔧 Advanced Configuration
$3
| Variable | Default | Description |
|----------|---------|-------------|
| GIT_REPOSITORY | https://github.com/Klipper3d/klipper.git | Klipper repository URL |
| GIT_BRANCH | master | Repository branch |
| DATA_DIR | ./data | Local data directory |
| LOG_LEVEL | info | Logging level (debug, info, warn, error) |
| UPDATE_INTERVAL | 3600 | Auto-update interval in seconds |
$3
`bash
Build the image
docker build -t mcp-klipper-docs .
Run the container
docker run -d \
--name mcp-klipper-docs \
-v $(pwd)/data:/app/data \
mcp-klipper-docs
`
$3
`yaml
version: '3.8'
services:
mcp-klipper-docs:
build: .
container_name: mcp-klipper-docs
volumes:
- ./data:/app/data
environment:
- LOG_LEVEL=info
- UPDATE_INTERVAL=3600
restart: unless-stopped
`
---
📊 Performance Metrics
$3
- Documents: 56 Klipper documentation files
- Words: 135,000+ indexed words
- Sections: 11 categorized sections
- Build Time: ~400ms for full index
- Search Speed: <10ms for typical queries
$3
- Base Memory: ~50MB
- Index Memory: ~25MB
- Peak Memory: ~100MB during updates
$3
- Initial Clone: ~50MB (one-time)
- Updates: ~1-5MB (changes only)
- API Calls: Local only (no external dependencies)
---
🧪 Development
$3
`bash
Clone the repository
git clone https://github.com/yourusername/mcp-klipper-docs.git
cd mcp-klipper-docs
Install dependencies
npm install
Run in development mode
npm run dev
Run tests
npm test
Build for production
npm run build
`
$3
`
mcp-klipper-docs/
├── src/
│ ├── server.ts # Main MCP server
│ ├── config.ts # Configuration management
│ ├── logger.ts # Logging utilities
│ ├── git-sync.ts # Git repository operations
│ ├── parser.ts # Markdown document parsing
│ ├── search.ts # Search engine implementation
│ ├── types.ts # TypeScript type definitions
│ └── errors.ts # Error handling
├── tests/ # Test suite
├── docs/ # Additional documentation
├── img/ # Images and assets
├── data/ # Local Klipper repository
└── dist/ # Built JavaScript files
`
$3
`bash
Run all tests
npm test
Run tests in watch mode
npm run test:watch
Run with coverage
npm run test -- --coverage
Lint code
npm run lint
Fix linting issues
npm run lint:fix
`
---
🤝 Contributing
We welcome contributions from the Klipper community! Here's how you can help:
$3
1. Check existing issues first
2. Use the issue templates provided
3. Include:
- Steps to reproduce
- Expected vs actual behavior
- Environment details
- Relevant logs
$3
1. Open a discussion first for major features
2. Provide clear use cases
3. Consider implementation complexity
4. Think about edge cases
$3
1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes:
- Follow existing code style
- Add tests for new functionality
- Update documentation
4. Run the test suite: npm test
5. Submit a pull request
$3
- Fix typos and improve clarity
- Add examples and use cases
- Update README and guides
- Translate documentation (if you speak other languages)
---
📈 Roadmap
$3
- [ ] Enhanced Search: Fuzzy matching and spell correction
- [ ] Cross-references: Link related configuration options
- [ ] Version Support: Support multiple Klipper versions
- [ ] Performance: Optimized indexing and caching
$3
- [ ] Multi-language: Internationalization support
- [ ] Community Docs: User-contributed documentation
- [ ] AI Features: Smart recommendations and assistance
- [ ] Integration: Other AI assistant platforms
---
🙏 Acknowledgments
$3
- Model Context Protocol - For enabling AI assistant integration
- Klipper - For the excellent 3D printer firmware
- Lunr.js - For powerful search capabilities
- TypeScript - For type-safe development
$3
- Klipper Community - For maintaining comprehensive documentation
- MCP Community - For protocol development and support
- Open Source Contributors - For the tools and libraries we use
---
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
---
📞 Support & Community
$3
- 📖 Documentation: Check this README and the /docs folder
- 🐛 Issues: Report bugs on GitHub
- 💬 Discussions: Join GitHub Discussions
- 📦 npm Issues: Report package issues
$3
- Discord: Join the Klipper and MCP communities
- Reddit: r/klipper and r/3Dprinting
- Twitter/X: Follow @bpuhnk @klipper3d and MCP updates
$3
- Registry Entry: Available for MCP server discovery
- Installation: npm install -g mcp-klipper-docs`