# kicad-pcb-api
**Professional KiCAD PCB Manipulation Library with File-Based Operations**
A modern, high-performance Python library for programmatic manipulation of KiCAD PCB files (.kicad_pcb) with exact format preservation, advanced placement algorithms, and AI agent integration. Unlike KiCAD's official PCB API which requires a running KiCAD instance, kicad-pcb-api works directly with PCB files for CI/CD and automated workflows.
## 🚀 Key Features
- **📋 File-Based Operations**: Manipulate .kicad_pcb files without running KiCAD
- **⚡ Advanced Placement**: Force-directed, hierarchical, and spiral algorithms
- **🤖 AI Agent Integration**: Native MCP server for AI-assisted PCB design
- **🔧 Enhanced Routing**: Freerouting integration with DSN export/import
- **📚 Footprint Management**: Advanced footprint library integration
- **✅ Format Preservation**: Exact compatibility with KiCAD's native output
- **🎯 KiCAD 9 Optimized**: Built specifically for latest KiCAD PCB format
## 🆚 vs. Existing Solutions
| Feature | kicad-pcb-api | KiCAD Official API | pcbnew Python API |
|---------|---------------|-------------------|-------------------|
| **File Operations** | ✅ Direct file manipulation | ❌ Runtime only | ❌ Runtime only |
| **CI/CD Compatible** | ✅ No GUI required | ❌ Requires KiCAD | ❌ Requires KiCAD |
| **Placement Algorithms** | ✅ Multiple advanced | ⚠️ Basic | ⚠️ Manual |
| **Routing Integration** | ✅ Freerouting + DSN | ❌ Limited | ⚠️ Basic |
| **AI Integration** | ✅ Native MCP | ❌ None | ❌ None |
| **Format Preservation** | ✅ Exact | ✅ Native | ✅ Native |
## 📦 Installation
```bash
# Install from PyPI (coming soon)
pip install kicad-pcb-api
# Or install from source
git clone https://github.com/circuit-synth/kicad-pcb-api.git
cd kicad-pcb-api
pip install -e .
```
## 🎯 Quick Start
### Basic PCB Manipulation
```python
import kicad_pcb_api as kpa
# Load existing PCB
pcb = kpa.load_pcb('my_board.kicad_pcb')
# Add footprints
resistor = pcb.footprints.add(
'Resistor_SMD:R_0603_1608Metric',
reference='R1',
position=(50, 50)
)
# Update properties
resistor.value = '10k'
resistor.layer = 'F.Cu'
resistor.rotation = 90
# Save with format preservation
pcb.save()
```
### Advanced Placement
```python
# Automatic component placement
placer = kpa.placement.ForceDirectedPlacer(pcb)
placer.place_components(
algorithm='hierarchical',
optimize_for='trace_length'
)
# Custom placement strategies
spiral_placer = kpa.placement.SpiralPlacer(pcb)
spiral_placer.place_in_spiral(
components=['R1', 'R2', 'C1'],
center=(100, 100),
spacing=5.0
)
```
### Routing Integration
```python
# Export for routing
router = kpa.routing.FreeroutingRunner(pcb)
dsn_file = router.export_dsn('board.dsn')
# Import routed traces
router.import_routes('board.ses')
# Validate routing
issues = pcb.validate_routing()
```
## 🏗️ Architecture
```
kicad-pcb-api/
├── python/ # Core Python library
│ ├── kicad_pcb_api/
│ │ ├── core/ # Core PCB manipulation
│ │ ├── placement/ # Placement algorithms
│ │ ├── routing/ # Routing integration
│ │ ├── footprints/ # Footprint management
│ │ ├── mcp/ # MCP server interface
│ │ └── utils/ # Utilities and validation
│ └── tests/ # Comprehensive test suite
├── mcp-server/ # TypeScript MCP server
└── examples/ # Usage examples
```
## 🤝 Contributing
We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
## 📄 License
MIT License - see [LICENSE](LICENSE) for details.
---
**Built with ❤️ by the Circuit-Synth team**
Raw data
{
"_id": null,
"home_page": null,
"name": "kicad-pcb-api",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "ai-integration, automation, circuit-design, eda, electronics, kicad, pcb, placement, routing",
"author": null,
"author_email": "Circuit-Synth Team <contact@circuit-synth.com>",
"download_url": "https://files.pythonhosted.org/packages/3b/f3/488cf46bb6ee7988fa8557db950dc6d0158d86105f261777089bee4d9e9b/kicad_pcb_api-0.0.1.tar.gz",
"platform": null,
"description": "# kicad-pcb-api\n\n**Professional KiCAD PCB Manipulation Library with File-Based Operations**\n\nA modern, high-performance Python library for programmatic manipulation of KiCAD PCB files (.kicad_pcb) with exact format preservation, advanced placement algorithms, and AI agent integration. Unlike KiCAD's official PCB API which requires a running KiCAD instance, kicad-pcb-api works directly with PCB files for CI/CD and automated workflows.\n\n## \ud83d\ude80 Key Features\n\n- **\ud83d\udccb File-Based Operations**: Manipulate .kicad_pcb files without running KiCAD\n- **\u26a1 Advanced Placement**: Force-directed, hierarchical, and spiral algorithms\n- **\ud83e\udd16 AI Agent Integration**: Native MCP server for AI-assisted PCB design\n- **\ud83d\udd27 Enhanced Routing**: Freerouting integration with DSN export/import\n- **\ud83d\udcda Footprint Management**: Advanced footprint library integration\n- **\u2705 Format Preservation**: Exact compatibility with KiCAD's native output\n- **\ud83c\udfaf KiCAD 9 Optimized**: Built specifically for latest KiCAD PCB format\n\n## \ud83c\udd9a vs. Existing Solutions\n\n| Feature | kicad-pcb-api | KiCAD Official API | pcbnew Python API |\n|---------|---------------|-------------------|-------------------|\n| **File Operations** | \u2705 Direct file manipulation | \u274c Runtime only | \u274c Runtime only |\n| **CI/CD Compatible** | \u2705 No GUI required | \u274c Requires KiCAD | \u274c Requires KiCAD |\n| **Placement Algorithms** | \u2705 Multiple advanced | \u26a0\ufe0f Basic | \u26a0\ufe0f Manual |\n| **Routing Integration** | \u2705 Freerouting + DSN | \u274c Limited | \u26a0\ufe0f Basic |\n| **AI Integration** | \u2705 Native MCP | \u274c None | \u274c None |\n| **Format Preservation** | \u2705 Exact | \u2705 Native | \u2705 Native |\n\n## \ud83d\udce6 Installation\n\n```bash\n# Install from PyPI (coming soon)\npip install kicad-pcb-api\n\n# Or install from source\ngit clone https://github.com/circuit-synth/kicad-pcb-api.git\ncd kicad-pcb-api\npip install -e .\n```\n\n## \ud83c\udfaf Quick Start\n\n### Basic PCB Manipulation\n\n```python\nimport kicad_pcb_api as kpa\n\n# Load existing PCB\npcb = kpa.load_pcb('my_board.kicad_pcb')\n\n# Add footprints\nresistor = pcb.footprints.add(\n 'Resistor_SMD:R_0603_1608Metric', \n reference='R1', \n position=(50, 50)\n)\n\n# Update properties\nresistor.value = '10k'\nresistor.layer = 'F.Cu'\nresistor.rotation = 90\n\n# Save with format preservation\npcb.save()\n```\n\n### Advanced Placement\n\n```python\n# Automatic component placement\nplacer = kpa.placement.ForceDirectedPlacer(pcb)\nplacer.place_components(\n algorithm='hierarchical',\n optimize_for='trace_length'\n)\n\n# Custom placement strategies\nspiral_placer = kpa.placement.SpiralPlacer(pcb)\nspiral_placer.place_in_spiral(\n components=['R1', 'R2', 'C1'],\n center=(100, 100),\n spacing=5.0\n)\n```\n\n### Routing Integration\n\n```python\n# Export for routing\nrouter = kpa.routing.FreeroutingRunner(pcb)\ndsn_file = router.export_dsn('board.dsn')\n\n# Import routed traces\nrouter.import_routes('board.ses')\n\n# Validate routing\nissues = pcb.validate_routing()\n```\n\n## \ud83c\udfd7\ufe0f Architecture\n\n```\nkicad-pcb-api/\n\u251c\u2500\u2500 python/ # Core Python library\n\u2502 \u251c\u2500\u2500 kicad_pcb_api/\n\u2502 \u2502 \u251c\u2500\u2500 core/ # Core PCB manipulation\n\u2502 \u2502 \u251c\u2500\u2500 placement/ # Placement algorithms\n\u2502 \u2502 \u251c\u2500\u2500 routing/ # Routing integration\n\u2502 \u2502 \u251c\u2500\u2500 footprints/ # Footprint management\n\u2502 \u2502 \u251c\u2500\u2500 mcp/ # MCP server interface\n\u2502 \u2502 \u2514\u2500\u2500 utils/ # Utilities and validation\n\u2502 \u2514\u2500\u2500 tests/ # Comprehensive test suite\n\u251c\u2500\u2500 mcp-server/ # TypeScript MCP server\n\u2514\u2500\u2500 examples/ # Usage examples\n```\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n## \ud83d\udcc4 License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n**Built with \u2764\ufe0f by the Circuit-Synth team**",
"bugtrack_url": null,
"license": null,
"summary": "Professional KiCAD PCB Manipulation Library with File-Based Operations",
"version": "0.0.1",
"project_urls": {
"Documentation": "https://kicad-pcb-api.readthedocs.io",
"Homepage": "https://github.com/circuit-synth/kicad-pcb-api",
"Issues": "https://github.com/circuit-synth/kicad-pcb-api/issues",
"Repository": "https://github.com/circuit-synth/kicad-pcb-api"
},
"split_keywords": [
"ai-integration",
" automation",
" circuit-design",
" eda",
" electronics",
" kicad",
" pcb",
" placement",
" routing"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c5ba5f49d56a3a74f41b7d99d5206f8942b5458dae6a251fbccc48cbc902867c",
"md5": "8cab8d24e49d5e4122cecc08ef55c988",
"sha256": "0dbe67faecf958a248ba283bd76c3a1ce84f4f4edda66981c6ee5f4cc865b0f5"
},
"downloads": -1,
"filename": "kicad_pcb_api-0.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8cab8d24e49d5e4122cecc08ef55c988",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 91883,
"upload_time": "2025-08-14T02:27:39",
"upload_time_iso_8601": "2025-08-14T02:27:39.131689Z",
"url": "https://files.pythonhosted.org/packages/c5/ba/5f49d56a3a74f41b7d99d5206f8942b5458dae6a251fbccc48cbc902867c/kicad_pcb_api-0.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "3bf3488cf46bb6ee7988fa8557db950dc6d0158d86105f261777089bee4d9e9b",
"md5": "d4c515689fa46aeb4e555f4c83c51529",
"sha256": "73a679aa34f05480e2f743dafd47c40a0cdd419101b829954242ef82400dd84f"
},
"downloads": -1,
"filename": "kicad_pcb_api-0.0.1.tar.gz",
"has_sig": false,
"md5_digest": "d4c515689fa46aeb4e555f4c83c51529",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 77735,
"upload_time": "2025-08-14T02:27:40",
"upload_time_iso_8601": "2025-08-14T02:27:40.292346Z",
"url": "https://files.pythonhosted.org/packages/3b/f3/488cf46bb6ee7988fa8557db950dc6d0158d86105f261777089bee4d9e9b/kicad_pcb_api-0.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-14 02:27:40",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "circuit-synth",
"github_project": "kicad-pcb-api",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "kicad-pcb-api"
}
JSON
