# @nvanexan/figma-mcp

Figma MCP server for GitHub Copilot coding agent — PAT auth via STDIO.

Extracts design context (layout, styles, typography, effects) from Figma files as CSS-like properties, and exports rendered images of Figma nodes. Built on the [Model Context Protocol](https://modelcontextprotocol.io/).

## Install

```bash
npm install -g @nvanexan/figma-mcp
```

Or use directly with npx:

```bash
npx @nvanexan/figma-mcp
```

## Setup

Set your Figma Personal Access Token as an environment variable:

```bash
export FIGMA_API_KEY=your-figma-pat
```

You can generate a token in Figma under **Settings > Personal Access Tokens**.

### GitHub Copilot / Claude Code

Add the server to your MCP configuration:

```json
{
  "mcpServers": {
    "figma": {
      "command": "npx",
      "args": ["-y", "@nvanexan/figma-mcp"],
      "env": {
        "FIGMA_API_KEY": "your-figma-pat"
      }
    }
  }
}
```

## Tools

### `get_figma_context`

Extracts design context from a Figma URL and returns a simplified node tree with CSS-like properties (flexbox layout, colors, typography, effects, dimensions).

| Parameter | Type   | Required | Description                           |
| --------- | ------ | -------- | ------------------------------------- |
| `figmaUrl`| string | yes      | Figma file URL (with optional node-id)|
| `depth`   | number | no       | Node tree depth, 1–10 (default: 3)   |

### `get_figma_image`

Exports a rendered image of a Figma node.

| Parameter | Type   | Required | Description                          |
| --------- | ------ | -------- | ------------------------------------ |
| `figmaUrl`| string | yes      | Figma URL with a node-id             |
| `format`  | string | no       | `png`, `jpg`, `svg`, `pdf` (default: `png`) |
| `scale`   | number | no       | 0.01–4 (default: 2)                 |

## Development

```bash
npm install
npm run build
npm test
```

### Scripts

| Script             | Description                        |
| ------------------ | ---------------------------------- |
| `npm run build`    | Compile TypeScript to `dist/`      |
| `npm run lint`     | Lint source with ESLint            |
| `npm test`         | Run tests                          |
| `npm run test:watch` | Run tests in watch mode          |
| `npm run test:coverage` | Run tests with coverage report |

## Releasing

This project uses GitHub Actions for CI and publishing.

**To release a new version:**

1. Update the version in `package.json` following [semver](https://semver.org/):
   ```bash
   npm version patch  # 0.1.0 → 0.1.1 (bug fixes)
   npm version minor  # 0.1.0 → 0.2.0 (new features)
   npm version major  # 0.1.0 → 1.0.0 (breaking changes)
   ```
2. Push the commit and tag:
   ```bash
   git push origin main --follow-tags
   ```
3. The CI pipeline will automatically run tests and publish to npm.

## License

MIT