Content
# MCP Modus
<div align="left">
<img src="assets/hero_modus_mcp.png" alt="Modus 2 MCP" width="600">
</div>
<a href="https://glama.ai/mcp/servers/@julianoczkowski/mcp-modus">
<img width="380" height="200" src="https://glama.ai/mcp/servers/@julianoczkowski/mcp-modus/badge" alt="Modus MCP server" />
</a>
[](https://www.npmjs.com/package/@julianoczkowski/mcp-modus)
[](https://opensource.org/licenses/MIT)
**AI assistant for Modus Web Components** - Get instant help with component documentation, design rules, and setup guides directly in your IDE.
## What This Does
This MCP server gives AI assistants (like Cursor, Claude, VS Code) access to complete Modus Web Components documentation. Ask questions like:
- _"How do I use a Modus button with primary color?"_
- _"What are the Modus color guidelines?"_
- _"Show me how to set up a React project with Modus components"_
- _"Which components have a disabled attribute?"_
## Setup
Choose one of the two options below:
### Option 1: NPX (Recommended - No Installation)
**For any IDE with MCP support:**
```json
{
"mcpServers": {
"modus-docs": {
"command": "npx",
"args": ["-y", "@julianoczkowski/mcp-modus"]
}
}
}
```
**Benefits:** No installation required, always uses latest version, no permission issues, secure pre-bundled documentation.
### Option 2: Global Install
1. **Install globally:**
```bash
npm install -g @julianoczkowski/mcp-modus
```
> **Note**: On some systems, you may need `sudo npm install -g @julianoczkowski/mcp-modus`
2. **Use this config:**
```json
{
"mcpServers": {
"modus-docs": {
"command": "mcp-modus"
}
}
}
```
**Benefits:** Faster startup, works offline after installation, secure pre-bundled documentation.
## IDE-Specific Instructions
### For Cursor IDE
1. Go to `Settings → Features → MCP`
2. Click "Add New MCP Server"
3. Use one of the JSON configs above
### For VS Code (with Continue)
Add to `~/.continue/config.json` using one of the JSON configs above.
### For Claude Desktop
Add to your config file using one of the JSON configs above:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%/Claude/claude_desktop_config.json`
## What You Get
### 📚 **Component Documentation** (49 components)
Complete API documentation for all Modus Web Components including attributes, events, methods, slots, and usage examples.
<details>
<summary><strong>View all 49 components</strong></summary>
| Component | Description |
| -------------------------- | --------------------------------------- |
| `modus-wc-accordion` | Expandable/collapsible content sections |
| `modus-wc-alert` | Contextual feedback messages |
| `modus-wc-autocomplete` | Text input with suggestions |
| `modus-wc-avatar` | User profile images |
| `modus-wc-badge` | Status indicators and labels |
| `modus-wc-breadcrumbs` | Navigation path indicators |
| `modus-wc-button` | Interactive action buttons |
| `modus-wc-button-group` | Grouped buttons with selection modes |
| `modus-wc-card` | Content container with elevation |
| `modus-wc-checkbox` | Boolean input control |
| `modus-wc-chip` | Compact interactive elements |
| `modus-wc-collapse` | Animated show/hide content |
| `modus-wc-date` | Date picker input |
| `modus-wc-divider` | Visual content separator |
| `modus-wc-dropdown-menu` | Contextual menu with trigger |
| `modus-wc-file-dropzone` | Drag-and-drop file upload |
| `modus-wc-handle` | Resizable panel divider |
| `modus-wc-icon` | Modus icon display |
| `modus-wc-input-feedback` | Form validation messages |
| `modus-wc-input-label` | Form field labels |
| `modus-wc-loader` | Loading state indicators |
| `modus-wc-logo` | Trimble/Viewpoint brand logos |
| `modus-wc-menu` | Navigation menu container |
| `modus-wc-menu-item` | Menu navigation items |
| `modus-wc-modal` | Dialog overlays |
| `modus-wc-navbar` | Top navigation bar |
| `modus-wc-number-input` | Numeric input with controls |
| `modus-wc-pagination` | Page navigation controls |
| `modus-wc-panel` | Structured layout container |
| `modus-wc-progress` | Progress indicators |
| `modus-wc-radio` | Single-select option control |
| `modus-wc-rating` | Star rating input |
| `modus-wc-select` | Dropdown selection input |
| `modus-wc-side-navigation` | Sidebar navigation |
| `modus-wc-skeleton` | Loading placeholder |
| `modus-wc-slider` | Range value selector |
| `modus-wc-stepper` | Multi-step process indicator |
| `modus-wc-switch` | Toggle on/off control |
| `modus-wc-table` | Data table display |
| `modus-wc-tabs` | Tabbed content navigation |
| `modus-wc-text-input` | Single-line text input |
| `modus-wc-textarea` | Multi-line text input |
| `modus-wc-theme-switcher` | Theme selection control |
| `modus-wc-time-input` | Time picker input |
| `modus-wc-toast` | Notification messages |
| `modus-wc-toolbar` | Action button container |
| `modus-wc-tooltip` | Contextual hover information |
| `modus-wc-typography` | Text styling component |
| `modus-wc-utility-panel` | Slide-out utility panel |
</details>
### 🎨 **Design System Rules** (6 guides)
Comprehensive design guidelines for building consistent Modus applications.
| Guide | Coverage |
| --------------- | --------------------------------------------- |
| `modus_colors` | Color tokens, semantic colors, theme palettes |
| `modus_icons` | Icon names, sizes, usage guidelines |
| `typography` | Font families, sizes, weights, line heights |
| `spacing` | Spacing scale, margins, padding values |
| `breakpoints` | Responsive breakpoints, media queries |
| `radius_stroke` | Border radius values, stroke widths |
### ⚙️ **Project Setup Guides** (5 guides)
Step-by-step instructions for integrating Modus Web Components.
| Guide | Coverage |
| ----------------- | --------------------------------------------------------- |
| `setup_html` | HTML project setup, CDN usage, basic integration |
| `setup_react` | React project setup, npm installation, component usage |
| `theme_usage` | Theme implementation, light/dark modes, customization |
| `testing` | Testing guidelines, accessibility testing, best practices |
| `universal_rules` | General development rules, coding standards |
## Example Usage
Once configured, ask your AI assistant:
```
"Create a Modus button with warning color and medium size"
"What spacing values should I use in my Modus design?"
"How do I set up a new React project with Modus Web Components?"
"Show me all Modus form components"
"What are the available Modus color tokens?"
```
The AI will use the MCP server to fetch the latest documentation and provide accurate, up-to-date answers.
## Security & Reliability
- **🔒 Pre-bundled Documentation**: All documentation is included with the package - no runtime downloads
- **🛡️ No External Dependencies**: Runs completely offline after installation
- **✅ Verified Content**: Documentation is verified during our CI/CD process
- **🚀 Fast & Secure**: No network requests during operation
- **🔐 Secure Publishing**: Uses npm Trusted Publishers (OIDC) for secure, automated releases with automatic provenance attestation
## Troubleshooting
### Server Not Connecting
- Ensure Node.js 20+ is installed: `node --version` (required for npm 11.5.1+ which supports OIDC)
- For global install: verify with `mcp-modus --help`
- Check IDE logs for error messages
### Documentation Updates
**Documentation is pre-bundled** with each release for security and reliability. No downloads occur during installation or runtime.
### Uninstalling
If you used the **NPX option** (Option 1), no permanent installation exists. NPX downloads are temporary.
If you used the **Global Install option** (Option 2), uninstall with:
```bash
npm uninstall -g @julianoczkowski/mcp-modus
```
### Need Help?
- [GitHub Issues](https://github.com/julianoczkowski/mcp-modus/issues)
- [Modus Web Components Docs](https://modus.trimble.com/)
---
**Built for developers using Modus Web Components** | **MIT License** | **Made by Julian Oczkowski**
## Author
<img width="236" height="236" alt="avatar2" src="https://github.com/user-attachments/assets/5677ddb5-6b0b-4054-a70b-a143761dd307" />
Built by **Julian Oczkowski** — I build AI tools for knowledge work.
- 🎥 **[YouTube · @aiforwork_app](https://www.youtube.com/@aiforwork_app)** — walkthroughs and AI-for-work tutorials
- ✍️ **[Medium](https://medium.com/@julian.oczkowski)** — deep dives on product and AI workflows
- 💼 **[LinkedIn](https://www.linkedin.com/in/julianoczkowski/)** — connect and follow along
