README.npm.md

# mcp-figma-comment-summary

> MCP server to retrieve, analyze, and create Figma file comments with Claude Desktop

[![npm version](https://img.shields.io/npm/v/mcp-figma-comment-summary.svg)](https://www.npmjs.com/package/mcp-figma-comment-summary)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A [Model Context Protocol](https://modelcontextprotocol.io/) server that enables Claude Desktop to retrieve, analyze, and create comments in Figma files. Perfect for design review workflows, team collaboration analysis, and comment management.

## 🎯 What Can This Do?

This MCP gives Claude **full read and write access** to Figma comments:

**📖 Reading:** Get comments, view authors/timestamps/locations, generate summaries
**✍️ Writing:** Create new comments, reply to threads, post on specific elements
**🤖 AI Workflows:** Auto-respond to feedback, analyze designs, coordinate reviews

## Features

- 📝 Retrieve all comments from any Figma file with full details
- ✍️ Create new comments and reply to existing ones
- 👥 Extract author information, timestamps, and reply threads
- 📊 Generate automatic summaries with statistics by author, location, and resolution status
- 📍 Post comments to specific locations (nodes or coordinates)
- 🔧 Easy integration with Claude Desktop and any MCP client
- 🔒 Each user uses their own Figma token (secure and private)

## Quick Start

### Prerequisites

- Node.js 18 or higher
- A [Figma Personal Access Token](https://www.figma.com/developers/api#access-tokens)
- Claude Desktop or any MCP-compatible client

### Installation

Add this to your Claude Desktop configuration file:

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`  
**Windows:** `%APPDATA%/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "figma-comments": {
      "command": "npx",
      "args": ["-y", "mcp-figma-comment-summary"],
      "env": {
        "FIGMA_ACCESS_TOKEN": "your_figma_token_here"
      }
    }
  }
}
```

**Important:** Replace `your_figma_token_here` with your actual Figma Personal Access Token.

### Getting Your Figma Token

1. Go to [Figma Settings → Account](https://www.figma.com/settings)
2. Scroll to "Personal access tokens"
3. Click "Generate new token"
4. Give it a name and copy the token
5. Paste it in the configuration above

### Restart Claude Desktop

After updating the configuration, completely quit and restart Claude Desktop to load the MCP server.

## Available Tools

### 1. `get_figma_comments`

Retrieve all comments from a Figma file with complete information.

**Parameters:**
- `file_id` (string, required): The Figma file ID from the URL

**Example usage in Claude:**
```
Get all comments from Figma file ABC123XYZ
```

**Returns:**
```json
[
  {
    "id": "comment_id",
    "message": "Comment text",
    "author": {
      "id": "user_id",
      "handle": "username",
      "img_url": "avatar_url"
    },
    "timestamp": "2024-01-01T00:00:00Z",
    "resolvedAt": null,
    "location": {
      "node_id": "node_id",
      "x": 100,
      "y": 200
    },
    "replies": [...]
  }
]
```

### 2. `summarize_figma_comments`

Generate a summary and analysis of all comments in a Figma file.

**Parameters:**
- `file_id` (string, required): The Figma file ID from the URL

**Example usage in Claude:**
```
Summarize the comments from Figma file ABC123XYZ
```

**Returns:**
```json
{
  "summary": {
    "total_comments": 10,
    "total_replies": 5,
    "resolved": 3,
    "unresolved": 7
  },
  "by_author": {
    "username1": {"comments": 5, "replies": 2}
  },
  "by_location": {
    "node_id_1": 3
  },
  "comments": [...]
}
```

## Finding the Figma File ID

The File ID is in your Figma file URL:

```
https://www.figma.com/file/ABC123XYZ/file-name
                          ↑
                    This is the File ID
```

## Use Cases

- **Design Reviews:** Quickly gather all feedback and comments from stakeholders
- **Team Collaboration:** Analyze comment patterns and identify bottlenecks
- **Comment Management:** Find unresolved comments and track resolution status
- **Reporting:** Generate summaries for design sprint retrospectives
- **AI Analysis:** Let Claude analyze comment sentiment and extract action items

## Example Conversations with Claude

Once installed, you can ask Claude:

```
"Get all comments from Figma file ABC123 and tell me which ones are unresolved"

"Summarize the feedback on file XYZ123 and identify common themes"

"Show me all comments by username 'john' in file ABC123"

"Which design elements in file XYZ have the most comments?"
```

## Verification

To verify the installation:

1. Open Claude Desktop
2. Look for the tools icon (🔧) in the interface
3. You should see "figma-comments" listed as an available server
4. The tools `get_figma_comments` and `summarize_figma_comments` should appear

## Troubleshooting

### "FIGMA_ACCESS_TOKEN environment variable is required"

- Ensure your token is correctly set in `claude_desktop_config.json`
- Verify the token is valid at [Figma Settings](https://www.figma.com/settings)

### Server doesn't appear in Claude Desktop

- Check that the configuration file path is correct
- Ensure you completely quit and restarted Claude Desktop (not just closed the window)
- Check Claude Desktop logs for errors

### Error fetching comments

- Verify the File ID is correct
- Ensure you have access permissions to the Figma file
- Your token must have read permissions for the file

## Development

To run the server locally for development:

```bash
git clone https://github.com/cloudframework-io/mcp-figma-comment-summary.git
cd mcp-figma-comment-summary
npm install
npm run dev
```

## Related Resources

- [Model Context Protocol Documentation](https://modelcontextprotocol.io/)
- [Figma API Documentation](https://www.figma.com/developers/api)
- [Claude Desktop](https://claude.ai/download)

## License

MIT

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Support

If you encounter any issues or have questions:
- Open an issue on [GitHub](https://github.com/cloudframework-io/mcp-figma-comment-summary/issues)
- Check the [Figma API documentation](https://www.figma.com/developers/api)

---

Made with ❤️ for the MCP community