使用说明

🎨 Figma MCP服务器

一个生产就绪的模型上下文协议（MCP）服务器，将Figma与Claude等人工智能助手无缝集成。具有自动令牌刷新的OAuth功能，无需每30天手动更新一次令牌。

✨ 主要特点

🔐 OAuth自动刷新：不再手动更新Figma代币-每30天自动刷新一次
🤖 MCP协议支持：与Claude和其他人工智能助手完全集成
🚀 多个部署选项：部署到Vercel、Railway、Render或自主机
🛡️ 企业安全：Auth0、OAuth 2.0、API密钥身份验证和速率限制
📊 完整的Figma API覆盖范围：所有主要的Figma操作均可通过MCP工具访问
🔄 实时更新：WebSocket支持实时协作功能
📦 TypeScript SDK：用于Node.js应用程序的全类型客户端SDK
📚 综合文档：详细的API参考资料、集成指南和示例

🚀 快速开始

先决条件

Node.js 18+和npm
Figma帐户个人访问令牌或OAuth应用程序
PostgreSQL数据库（对于OAuth是必需的，对于API密钥验证是可选的）
（可选）Redis用于速率限制

安装

# Clone the repository
git clone https://github.com/haseebrj17/figma-mcp-server.git
cd figma-mcp-server

# Install dependencies
npm install

# Copy environment variables
cp .env.example .env

# Set up database (interactive setup wizard)
npm run setup:db

# Or manually configure .env and run:
# npm run prisma:generate
# npm run prisma:migrate

# Start development server
npm run dev

🔧 配置

环境变量

创建一个 .env 文件基于 .env.example:

# Server Configuration
NODE_ENV=development
PORT=3000
SERVER_URL=http://localhost:3000

# Authentication Method (choose one)
AUTH_METHOD=oauth  # Options: 'oauth', 'apikey', 'auth0'

# Figma OAuth (recommended for production)
FIGMA_CLIENT_ID=your-figma-client-id
FIGMA_CLIENT_SECRET=your-figma-client-secret
FIGMA_REDIRECT_URI=http://localhost:3000/auth/callback

# OR Figma Personal Token (for development)
FIGMA_ACCESS_TOKEN=your-personal-access-token

# Database (required for OAuth)
DATABASE_URL=postgresql://user:password@localhost:5432/figma_mcp

# Optional: Redis for rate limiting
REDIS_URL=redis://localhost:6379

# Optional: Monitoring
SENTRY_DSN=your-sentry-dsn

身份验证方法

1. OAuth自动刷新（推荐）

实现带有自动令牌刷新的Figma OAuth 2.0：

// Tokens are automatically refreshed before expiry
// No manual intervention needed

2. API密钥验证

服务器到服务器的简单基于密钥的身份验证：

AUTH_METHOD=apikey
API_KEY=your-secure-api-key

3. Auth0集成

具有Auth0的企业SSO：

AUTH_METHOD=auth0
AUTH0_DOMAIN=your-domain.auth0.com
AUTH0_CLIENT_ID=your-client-id
AUTH0_CLIENT_SECRET=your-secret

📚 可用的MCP工具

服务器将这些Figma操作作为MCP工具公开：

工具	说明	参数
`get_file`	检索完整的文件数据	`fileKey`, `branch_data`, `version`, `depth`
`get_file_nodes`	从文件中获取特定节点	`fileKey`, `nodeIds`, `version`, `depth`
`get_file_images`	从节点导出图像	`fileKey`, `nodeIds`, `format`, `scale`
`get_file_styles`	获取文件中的所有样式	`fileKey`
`get_file_components`	获取所有组件	`fileKey`
`get_team_projects`	列出团队项目	`teamId`
`get_project_files`	列出项目中的文件	`projectId`
`get_file_comments`	获取文件注释	`fileKey`
`post_file_comment`	发表新评论	`fileKey`, `message`, `client_meta`
`get_file_versions`	获取版本历史记录	`fileKey`

Claude使用示例

// In Claude or any MCP client
const result = await mcp.callTool('get_file', {
  fileKey: 'abc123xyz',
  depth: 2
});

// Export images from specific nodes
const images = await mcp.callTool('get_file_images', {
  fileKey: 'abc123xyz',
  nodeIds: ['1:2', '3:4'],
  format: 'png',
  scale: 2
});

🖥️ 客户端SDK

安装

npm install figma-mcp-client

用法

import { FigmaMCPClient } from 'figma-mcp-client';

// Initialize client
const client = new FigmaMCPClient({
  serverUrl: 'https://your-server.vercel.app',
  apiKey: 'your-api-key',
  transport: 'http' // or 'websocket'
});

// Connect to server
await client.connect();

// Use Figma tools
const file = await client.getFile('your-file-key');
const components = await client.getComponents('your-file-key');

// Export images
const images = await client.exportImages('your-file-key', ['node-id-1', 'node-id-2'], {
  format: 'png',
  scale: 2
});

🌐 API终点

MCP协议端点

GET /mcp/tools
Authorization: Bearer <token>

POST /mcp/tools/call
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "get_file",
  "arguments": {
    "fileKey": "abc123xyz"
  }
}

REST API端点

GET /api/files/:fileKey
GET /api/files/:fileKey/nodes?ids=1:2,3:4
GET /api/files/:fileKey/images?ids=1:2&format=png&scale=2
GET /api/files/:fileKey/styles
GET /api/files/:fileKey/components
GET /api/teams/:teamId/projects
GET /api/projects/:projectId/files
GET /api/files/:fileKey/comments
POST /api/files/:fileKey/comments
GET /api/files/:fileKey/versions

OAuth端点

GET /auth/figma                 # Start OAuth flow
GET /auth/callback              # OAuth callback
POST /auth/refresh              # Refresh access token
GET /auth/status                # Check auth status
POST /auth/logout               # Logout user

🚢 部署

部署到Vercel

# Install Vercel CLI
npm i -g vercel

# Deploy
vercel --prod

部署到铁路

点击“在铁路上部署”
配置环境变量
部署

部署以渲染

单击“部署以渲染”
配置构建和启动命令：
- 构建： npm run build
- 开始： npm run start

Docker部署

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build
RUN npm run prisma:generate
EXPOSE 3000
CMD ["npm", "start"]

docker build -t figma-mcp-server .
docker run -p 3000:3000 --env-file .env figma-mcp-server

🛠️ 发展

可用脚本

npm run dev          # Start development server with hot reload
npm run build        # Build TypeScript to JavaScript
npm run start        # Run production server
npm run test         # Run test suite
npm run lint         # Lint code with ESLint
npm run typecheck    # Type check with TypeScript

# Database commands
npm run setup:db         # Interactive database setup wizard
npm run prisma:generate  # Generate Prisma client
npm run prisma:migrate   # Run migrations (dev)
npm run prisma:deploy    # Deploy migrations (prod)
npm run prisma:studio    # Open Prisma Studio GUI
node test-db-connection.js # Test database connection

# Deployment
npm run vercel-build     # Build for Vercel

项目结构

figma-mcp-server/
├── src/
│   ├── index.ts           # Main MCP server entry
│   ├── http-server.ts     # Express HTTP server
│   ├── services/
│   │   ├── auth.ts        # Authentication service
│   │   ├── figma.ts       # Figma API wrapper
│   │   ├── oauth.ts       # OAuth implementation
│   │   └── prisma.ts      # Database client
│   ├── routes/
│   │   └── oauth.ts       # OAuth routes
│   └── types/
│       └── figma.ts       # Type definitions
├── client-sdk/            # TypeScript SDK
│   ├── src/
│   └── examples/
├── docs/                  # Documentation
│   ├── QUICKSTART.md      # Quick start guide
│   ├── API_REFERENCE.md   # Complete API documentation
│   ├── INTEGRATION_GUIDE.md # Platform integrations
│   ├── EXAMPLES.md        # Code examples
│   ├── DEPLOYMENT.md      # Deployment guide
│   └── MIGRATION_GUIDE.md # Migration guide
├── prisma/
│   └── schema.prisma      # Database schema
├── tests/                 # Test files
├── .env.example          # Environment template
├── CLAUDE.md             # AI assistant instructions
└── README.md             # This file

🔒 安全

最佳实践

✅ 从不提交代币：使用环境变量
✅ 在生产环境中使用OAuth：自动令牌刷新防止过期
✅ 启用速率限制：防止滥用
✅ 验证输入：所有输入都使用Zod模式进行验证
✅ 使用HTTPS：始终在生产中使用SSL
✅ 实施CSP：包含内容安全策略标头
✅ 定期更新：保持依赖关系更新

速率限制

// Built-in rate limiting per user
const rateLimiter = {
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 100 // limit each user to 100 requests per window
};

📖 文档

综合文档

该项目包括大量文档，以帮助您集成和使用Figma MCP服务器：

快速入门指南 -在5分钟内起床跑步
api参考 -完整的API文档，包括所有端点、参数和示例
集成指南 -与Claude、LangChain、OpenAI等集成的分步指南
例子 -常见用例和完整应用程序的完整代码示例
部署指导 -部署到Vercel、Railway、Render或自主机
迁移指南 -从个人令牌迁移到OAuth
数据库设置 -使用Prisma ORM设置PostgreSQL

快速链接

基本URL: https://figma-mcp-server-nu.vercel.app
健康检查: GET /api/health
列出工具: GET /api/mcp/tools
执行工具: POST /api/mcp/tools/call

🤝 贡献

我们欢迎捐款！请查看我们的贡献指南了解详情。

分叉存储库
创建功能分支(git checkout -b feature/amazing-feature)
提交您的更改(git commit -m 'Add amazing feature')
推到分支(git push origin feature/amazing-feature)
打开拉取请求

🐛 故障排除

常见问题

令牌到期

解决方案：启用OAuth并自动刷新
临时：更新 FIGMA_ACCESS_TOKEN 在……里面 .env

数据库连接失败

检查 DATABASE_URL 格式
确保PostgreSQL正在运行
运行迁移： npm run prisma:migrate

速率限制

配置Redis进行分布式速率限制
调整限制 rateLimiter 配置

CORS 问题

将您的域名添加到 ALLOWED_ORIGINS
检查 Access-Control-Allow-Origin 标头

📄 许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

🙏 致谢

图API 为优秀的API
模型上下文协议对于MCP规范
Anthropic 适用于Claude和MCP SDK
本项目的所有贡献者和用户

📞 支持

📧 电子邮件：mhaseeb@rainmakerz.app
🐛 问题： GitHub问题
📚 文件：文档

Made with ❤️ by Muhammad Haseeb

GitHub • NPM • Documentation