Eagle

This Eagle MCP Server provides a bridge between Eagle and external clients via the Model Context Protocol (MCP). It lets you manage Eagle assets and metadata through HTTP requests or a local stdio transport, enabling automation, tooling, and advanced workflows while Eagle runs the core application.

How to use

You connect an MCP client to the Eagle MCP Server using either the HTTP endpoint or the local stdio transport. Start the Eagle app, then start the MCP server, and your client can perform operations such as listing items, creating folders, or retrieving item information. The HTTP method exposes a remote API at the configured URL, while the stdio method runs the MCP server as a local process that you control from your development environment.

How to install

Prerequisites: install Python 3.13 and the uv command runner.

Install the MCP runtime utilities and dependencies with the following command.

uv sync

Next, ensure the Eagle app is running. Then start the MCP server with the command below.

uv run main.py

Configuration and usage details

Two connection methods are supported for the MCP Server. Use the HTTP approach for a remote client to connect to Eagle, or use the stdio transport to run the MCP server locally alongside Eagle.

HTTP config example you can use to connect a client to the MCP server on your local machine.

{
  "mcpServers": {
    "eagle-mcp-server": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

If you prefer stdio transport, configure the MCP client to launch the local MCP server via uvx and the provided GitHub source.

{
  "mcpServers": {
    "eagle-mcp-server": {
      "command": "uvx",
      "args": [
        "--from", "git+https://github.com/tuki0918/eagle-mcp-server@fastmcp-stdio",
        "eagle-mcp-server"
      ]
    }
  }
}

Enabling Disabled Tools

Some tools are disabled by default. To enable these tools, locate the tool definition in the source, remove the tags=["Disabled"] line from the tool configuration, and restart the MCP server. This will make the previously disabled tools available for use.

Use cases and architecture notes

On the same host setup is straightforward: Eagle runs on one side and the MCP server on the other, both accessible locally. If you are using different hosts, ensure network access to the MCP server and proper routing between Eagle and client tooling.

The MCP server exposes endpoints for common operations such as retrieving application information, managing folders, adding items from URLs or paths, updating items, and handling library information. You can mix HTTP and stdio methods depending on your environment and tooling requirements.

Notes on API endpoints and tooling

The MCP Server provides a comprehensive set of endpoints including application info, folder manipulation, item management, item thumbnail and palette refresh, and library history and icons. Use these endpoints from your MCP client to automate workflows in Eagle.

Available tools

connect

Establishes a connection between the MCP client and Eagle MCP Server, enabling subsequent API calls to navigate and manage Eagle resources.

get_application_info

Fetches metadata about the Eagle application, including version and capabilities.

create_folder

Creates a new folder within Eagle's library, returning the folder identifier and metadata.

update_folder

Updates folder properties such as name or metadata to organize content.

get_folder_list

Retrieves the list of folders available in the current library.

get_folder_list_recent

Returns a list of recently accessed or modified folders.

add_item_from_url

Adds a new item to the library from a remote URL.

add_items_from_urls

Adds multiple items from a list of URLs in a single operation.

add_item_from_path

Adds a local file to the library from a filesystem path.

add_items_from_paths

Adds multiple local files to the library from their filesystem paths.

add_bookmark

Creates a bookmark to an item or folder for quick access.

get_item_info

Retrieves metadata for a specific item in the library.

get_item_source

Fetches the source data or original file for an item.

get_item_thumbnail

Generates or retrieves a thumbnail image for an item.

get_item_list

Lists items in the library with optional filtering and pagination.

move_item_to_trash

Moves an item to the trash or recycle bin within Eagle.

refresh_item_palette

Refreshes the color palette or palettes associated with an item.

refresh_item_thumbnail

Refreshes the thumbnail image for an item to reflect changes.

update_item

Updates the properties or metadata of an existing item.

get_library_info

Retrieves information about the current library, including its stats and metadata.

get_library_history

Provides historical data about library changes and actions.

switch_library

Switches the active library to another available library.

get_library_icon

Fetches the icon or emblem representing the library.