<div align="center">

<pre aria-label="OCTOBER">
  ___   ____ _____ ___  ____  _____ ____
 / _ \ / ___|_   _/ _ \| __ )| ____|  _ \
| | | | |     | || | | |  _ \|  _| | |_) |
| |_| | |___  | || |_| | |_) | |___|  _ <
 \___/ \____| |_| \___/|____/|_____|_| \_\
</pre>

# October Themes MCP

### Give any AI-generated interface a real design direction.

1,000+ curated systems for color, type, components, motion, and visual character.

[![npm](https://img.shields.io/npm/v/@october-dev/themes-mcp?style=flat-square&color=7C6CF0)](https://www.npmjs.com/package/@october-dev/themes-mcp)
[![MCP](https://img.shields.io/badge/MCP-server-28B8D8?style=flat-square)](#available-tools)
[![License](https://img.shields.io/badge/license-MIT-1C1B18?style=flat-square)](LICENSE)

</div>

---

**October Themes MCP is a free Model Context Protocol server for better AI-generated UI.** It gives your coding agent a complete, prompt-ready design system before implementation starts: semantic colors, typography, component treatments, effects, motion, and deliberate rules that keep the result from collapsing into generic dashboard styling.

No API key. No theme account. Add the server once and ask your agent for a design direction whenever you need one.

## Quickstart

Add the server to your MCP configuration:

```json
{
  "mcpServers": {
    "october-themes": {
      "command": "npx",
      "args": ["-y", "@october-dev/themes-mcp"]
    }
  }
}
```

Then ask your agent:

```text
Get a desktop-web theme, then use it to build the settings screen.
```

The agent calls `get_theme`, receives one complete design system, and uses it as context for the UI it generates.

## Client configuration

<details>
<summary><strong>Claude Desktop / Claude Code</strong></summary>

Add to `~/.claude/mcp.json`:

```json
{
  "mcpServers": {
    "october-themes": {
      "command": "npx",
      "args": ["-y", "@october-dev/themes-mcp"]
    }
  }
}
```

</details>

<details>
<summary><strong>Cursor</strong></summary>

Add to `.cursor/mcp.json` in your project:

```json
{
  "mcpServers": {
    "october-themes": {
      "command": "npx",
      "args": ["-y", "@october-dev/themes-mcp"]
    }
  }
}
```

</details>

<details>
<summary><strong>VS Code Copilot</strong></summary>

Add to `.vscode/mcp.json`:

```json
{
  "servers": {
    "october-themes": {
      "command": "npx",
      "args": ["-y", "@october-dev/themes-mcp"]
    }
  }
}
```

</details>

<details>
<summary><strong>Windsurf</strong></summary>

Add to `~/.windsurf/mcp.json`:

```json
{
  "mcpServers": {
    "october-themes": {
      "command": "npx",
      "args": ["-y", "@october-dev/themes-mcp"]
    }
  }
}
```

</details>

Any MCP client that can start a local stdio server can use the same command and arguments.

## Available tools

| Tool | Input | Result |
| --- | --- | --- |
| `get_theme` | Optional `platform` filter | A weighted-random, prompt-ready design system |
| `get_theme_by_id` | Theme ID or slug | The requested design system |

Supported platform filters:

| Platform | Designed for |
| --- | --- |
| `desktop-web` | Websites, dashboards, and SaaS applications |
| `mobile-app` | iOS and Android interfaces, including navigation and mobile interaction patterns |
| `game` | Browser games, including lighting, particles, HUDs, and motion |

Omit the platform to draw from the complete theme library.

## What a theme contains

Every response is ready to place directly in an agent's context:

- semantic color palette with concrete values;
- typography families, sizes, weights, and hierarchy;
- button, card, input, navigation, and layout treatments;
- shadows, gradients, transitions, and animation direction;
- platform-specific interaction guidance;
- mandatory non-genericness rules that establish a distinct visual point of view.

The server supplies direction, not UI code. Your agent still implements the interface in the framework and component system already used by your project.

## How it works

```text
Your request
    ↓
AI client calls get_theme
    ↓
October Themes MCP fetches one curated design system
    ↓
The design system enters the model's working context
    ↓
The agent builds your UI against that direction
```

The MCP server runs locally over stdio and makes a read-only request to October's public themes API. It does not require credentials and does not read or modify your project files on its own.

## Example prompts

```text
Get a mobile-app theme and redesign the onboarding flow around it.
```

```text
Fetch the industrial-neon theme and apply it to this dashboard without changing its information architecture.
```

```text
Choose a game theme before implementing the inventory HUD.
```

For predictable results, ask for the theme before the agent starts producing UI code.

## MCP server or Agent Skill?

Use this repository when your client supports MCP and you want the theme library exposed as tools. Use [October Themes Skill](https://github.com/october-dev/october-skill) when your harness supports Agent Skills and you prefer a `/inject-theme` workflow.

Both use the same curated theme library:

| | Themes MCP | Themes Skill |
| --- | --- | --- |
| Interface | MCP tools | `/inject-theme` skill |
| Theme selection | Agent calls a tool | Skill fetches and confirms a theme |
| Best fit | MCP-native clients | Skill-native harnesses |

## Development

```bash
git clone https://github.com/october-dev/october-mcp.git
cd october-mcp
npm install
npm run build
npm start
```

Set `OCTOBER_API_URL` to point development builds at another compatible API origin.

Contributions that improve client setup, error handling, tool descriptions, and protocol compatibility are welcome. Keep the server small: theme curation belongs in the library, while this package should remain a clear MCP bridge.

## License

October Themes MCP is licensed under the [MIT License](LICENSE).

---

<div align="center">

Curated by [October](https://october.dev), the AI-native canvas for building apps.

</div>