Important Notice:
The Eagle MCP plugin requires Eagle 4.0 Build 12 (2025-09-14) or later to function properly. It is currently still in the Beta testing phase, and overall stability has not yet fully matured. In addition, capabilities and performance may vary across different AI models, and AI may still produce errors or unexpected results. Users who choose to try this plugin are strongly advised to perform a complete backup of all data in advance and to carefully review the task scope and execution details before each Agent run, in order to avoid unintended data changes caused by Agent misjudgment or model limitations.

Eagle MCP allows AI assistants to directly access your Eagle library through MCP (Model Context Protocol), transforming tasks such as tagging, categorization, translation, and batch organization—previously requiring extensive manual effort—into workflows that can be completed using natural language.

For example, you can instruct the AI to analyze all cat-related tags in your library, detect synonymous or overlapping tags (e.g., cat / cats / feline), normalize them into a single standardized tag, and correct spelling errors. The AI will generate a proposed change list first and can apply the changes in batch after confirmation, minimizing repetitive manual work and review overhead.

This article provides a complete setup guide for Eagle MCP. Using Cursor as an example, it walks you through installing and launching the Eagle MCP Server, verifying the server endpoint, and configuring the MCP Client (tool side), enabling you to integrate AI into your asset management workflow from scratch.

What Is MCP?

You can think of MCP (Model Context Protocol) as a “universal power outlet” for the AI world. It allows AI not only to chat, but—with your authorization—to read your real working content (data, files, knowledge) and operate the tools you actually use.

The following official Figma video explains very intuitively what an “MCP server” actually does. It is highly recommended to watch it first before diving into Eagle MCP—you will gain much clearer context.

What Can Eagle MCP Do?

Eagle MCP provides operation abstractions tailored specifically for design and creative asset management workflows.

Core Features

Intelligent Tag System Analysis

Analyzes your tag usage patterns to identify synonym groups (e.g., “cat / 貓 / 喵星人”), spelling variants, and usage frequency, then provides recommendations for merging, deprecating, or standardizing tags.
Natural Language Control for Complex Tasks

You can issue conditional queries and organization commands, such as limiting operations by folder, rating, time range, or existing tag sets.
Cloud and Local Model Integration

You may choose between cloud-based or local models depending on budget and privacy requirements (actual support depends on your MCP Client and model service).

Model Recommendation: Claude Sonnet 4.5 and Later
If you plan to use Eagle MCP for more complex or multi-step reasoning tasks (such as tag grouping analysis or batch classification suggestions), Claude Sonnet 4.5 and later versions are strongly recommended. The Claude series has been specifically trained for Tool Use, enabling more accurate understanding of MCP command structures and response formats. It is particularly stable in scenarios requiring repeated tool calls and structured outputs. For users with budget constraints, Claude Haiku 4.5 is an alternative option—while slightly less accurate in tool invocation, it offers better speed and cost efficiency, making it suitable for testing or non-critical tasks.

Installing the Eagle MCP Plugin

Step 1: Obtain the Eagle MCP Plugin

Open the Eagle application
From the top menu, select “Plugins” → “Plugin Center”
Enter “MCP” in the search bar
Locate “Eagle MCP” and click “Install”

Step 2: Complete Installation Setup

After installation, Eagle MCP will appear in the plugin list
Click “Enable” to activate the plugin
On first activation, the MCP server will start automatically (default port: 41596)
The system will display the server status: ✅ Running

MCP Server Configuration Guide

With the Eagle MCP server now ready, the next step is to configure connections in various mainstream AI tools. All configurations use the same server endpoint: http://127.0.0.1:41596/mcp.

Server Endpoint Configuration

Regardless of the AI tool you use, the basic Eagle MCP connection information remains the same:

{
  "mcpServers": {
    "eagle-mcp": {
      "transport": "http",
      "type": "streamable-http",
      "streamable": true,
      "url": "http://localhost:41596/mcp"
    }
  }
}

This endpoint enables AI tools to communicate with your local Eagle application and perform intelligent asset management operations.

Example Configuration Using Cursor

The Cursor editor offers a clean and developer-friendly MCP configuration experience.

Step 1: Open Cursor MCP Settings

Click the settings icon in the top-right corner and select Cursor Settings
Select Tools & MCP from the left panel

Step 2: Add the Eagle MCP Server

Click Add Custom MCP

Add the following configuration to mcp.json and save:

{
  "mcpServers": {
    "eagle-mcp": {
      "transport": "http",
      "type": "streamable-http",
      "streamable": true,
      "url": "http://localhost:41596/mcp"
    }
  }
}

Return to the MCP settings page. You should now see eagle-mcp listed. (If it shows “No Tools,” try toggling it off and on.)

Step 3: Test the Connection

Open Cursor’s AI chat panel
Ask the AI Agent: “What version of Eagle am I using?”
If MCP is correctly configured, the Agent will attempt to call Eagle MCP and request execution permission
Grant permission and execute. If the AI returns the correct answer, the Eagle MCP server is successfully configured.

Privacy and Data Exposure (Read Carefully)

Whether data “leaves your computer” when using Eagle MCP depends primarily on whether you use a cloud-based model or a local model.

If You Use a Cloud LLM

During inference, information such as filenames, tags, annotations, search criteria, and summaries may be transmitted to the model provider to generate responses.

Recommended Practices:

Avoid allowing Agents to batch-process highly sensitive assets (contracts, personal data, unreleased projects)
Start with small folders and expand only after confirming acceptable risk levels

If You Use a Local LLM

Data generally does not need to be sent to the cloud, resulting in lower privacy risk. However, quality, speed, and tool-calling stability can vary significantly between local models.

Note: The Eagle MCP server itself runs locally and translates AI instructions into controlled Eagle operations. Most data exposure occurs during model inference, not within MCP itself.

Permissions and Safety Best Practices

Eagle MCP is powerful—which also means it can make extensive changes. The following SOP is strongly recommended:

Analyze First, Execute Second: Ask the AI to produce a proposed change list before applying modifications
Start Small: Test with a limited number of files or a single folder before scaling up
Break Tasks Down: Avoid reorganizing the entire library in one command; use 2–5 smaller steps
Explicitly Limit Scope: Specify folders, file counts, time ranges, and tag sets
Begin with Read-Only Tasks: Verify versions, statistics, and candidate lists before batch edits

Eagle MCP Practical Examples (Copy & Paste Ready)

It is recommended to prepend each example with: “Please generate a change list first; do not execute immediately.” This helps build safe usage habits.

Example 1: Multilingual Tag Translation (Generate List First)

Please scan the tags within the folder "/Japan Assets".
Identify tags containing Japanese characters and translate them into English.
First output a mapping list of "Japanese Tag → English Tag" along with affected file counts.
After my confirmation, batch-add the English tags.

Example 2: Tag Usage Frequency Analysis and Cleanup Suggestions (Read-Only)

Please analyze my Eagle tag usage:
1) List tags used fewer than 3 times
2) Identify potentially synonymous or duplicated tag groups (including spelling errors)
3) Provide recommendations on which tags should be merged or deprecated
Generate a report only; do not make any changes.

Example 3: Classification Suggestions for Newly Added Files

Please analyze the 10 most recently added files.
Based on file types and my existing folder structure,
first propose a list of "recommended folder paths + recommended tags",
and include a confidence score or rationale for each suggestion.
After confirmation, proceed with moving files and applying tags.

Example 4: Single File Content Analysis and Complete Archival Recommendation

Please generate a change list first; do not execute immediately.

Analyze the currently selected file and complete the following steps:
1) Read the full file path and filename
2) Analyze the image content and generate a searchable, objective description
3) Propose a set of recommended tags (avoid overly abstract terms; prefer reusable keywords)
4) Recommend the most appropriate folder path based on my existing structure (single path only)

Output the following in list format:
- Filename
- Suggested description
- Suggested tags (list)
- Suggested folder path
- Rationale or confidence notes for each suggestion

After confirmation, proceed with writing the description, applying tags, and moving the file.

Example 5: Domain-Oriented Folder Structure for a New Library (Structure Only)

Please generate structure suggestions only; do not create any folders.

This is a brand-new, empty Eagle library intended for organizing "Game Design" inspiration images.

Please design a folder structure with the following requirements:
1) Approximately 5 top-level categories
2) Each top-level category should contain 5–10 subcategories
3) For each top-level category, provide:
   - Intended usage description
   - Suggested icon type
   - Icon color (avoid duplication across categories)

Output format:
- Top-level category name
  - Usage description
  - Icon suggestion (shape/type)
  - Icon color
  - Subcategory list (with brief descriptions)

The overall design should prioritize practical usability, long-term scalability, and longevity.
After confirmation, folders will be created.

FAQ (Troubleshooting)

Q1: MCP is configured but cannot connect / no response

Ensure Eagle is running and the Eagle MCP plugin shows ✅ Running
Verify the endpoint is correct: http://localhost:41596/mcp
Ensure mcp.json is valid JSON (a missing comma will break parsing)

Q2: eagle-mcp appears, but the Agent does not call tools

Disable and re-enable eagle-mcp
Test with read-only queries first (version, statistics, candidate lists)
Ensure the MCP Server is not disabled in Cursor’s tool/permission settings
Some models do not automatically decide to call tools—explicitly add “Please call eagle-mcp to query”

Q3: Results appear incorrect or unexpected

Request a “change list” and “impact scope” before applying changes
Break tasks into smaller steps, reduce folder scope, and limit batch size

Guide to the Eagle MCP Server