shingo1228/eagle-mcp-server

Eagle MCP Server

| English

A Modern Context Protocol (MCP) server implementation for Eagle App integration. This server enables AI assistants to interact with your Eagle library through a standardized interface with comprehensive tools and multilingual support.

✨ Features

• 🏗️ Modern Architecture: Pure MCP implementation built with mcp-python
• 🛠️ Comprehensive Tools: 16 high-level tools + 17 direct API tools for complete Eagle operations
• 🎛️ Configurable API Access: Toggle between user-friendly and advanced developer tools
• 🌏 Multilingual Support: Enhanced Japanese text handling and UTF-8 encoding
• 🖼️ Image Processing: Base64 encoding, thumbnail generation, and metadata analysis
• 🔌 Cross-platform: Compatible with LM Studio, Claude Desktop, and other MCP clients
• 🛡️ Robust Error Handling: Comprehensive error handling and logging
• ⚡ High Performance: Async implementation with efficient Eagle API integration
• 📝 Type Safe: Full type annotations with Pydantic validation

🚀 Quick Start

Prerequisites

• Python 3.11 or higher
• uv package manager
• Eagle App running locally (default: localhost:41595)

Installation

1. Clone the repository:

git clone https://github.com/shingo1228/eagle-mcp-server.git
cd eagle-mcp-server

2. Install dependencies:

uv sync

3. Start the server:

# Windows
run.bat

# Unix/Linux/macOS  
uv run main.py

🔧 Configuration

Environment Variables

Create a .env.local file for local configuration:

EAGLE_API_URL=http://localhost:41595
EAGLE_API_TIMEOUT=30.0
LOG_LEVEL=INFO

# Tool Configuration
EXPOSE_DIRECT_API_TOOLS=false  # Set to true for advanced API access

# Optional: Custom paths
# USER_DATA_DIR=/custom/path/to/data
# CACHE_DIR=/custom/path/to/cache

MCP Client Configuration

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "eagle-mcp-server": {
      "command": "/path/to/eagle-mcp-server/run.bat",
      "env": {
        "PYTHONPATH": "/path/to/eagle-mcp-server"
      }
    }
  }
}

LM Studio

Add to your MCP configuration:

{
  "mcpServers": {
    "eagle-mcp-server": {
      "command": "/path/to/eagle-mcp-server/run.bat",
      "env": {
        "PYTHONPATH": "/path/to/eagle-mcp-server"
      }
    }
  }
}

🛠️ Available Tools

Core Tools (Always Available)

Folder Management

Item Management

Image Processing

Library Management

Direct API Tools (Advanced)

💡 Note: Enable with EXPOSE_DIRECT_API_TOOLS=true for low-level Eagle API access (17 additional tools)

When enabled, provides direct access to Eagle's REST API endpoints for advanced users and developers.

🤖 AI Integration

System Prompts for AI Assistants

To help AI assistants effectively use Eagle MCP Server, we provide comprehensive system prompts:

• - Detailed guide with workflows and best practices
• - Quick reference for AI integration
• - 日本語版システムプロンプト

These prompts include:

• 33 tool usage patterns and workflows
• Best practices for efficient operations
• Error handling and user interaction guidelines
• Response format recommendations
• Performance optimization tips

Integration Examples

# Example: AI assistant using Eagle MCP Server
from mcp import ClientSession

# 1. Always start with health check
await session.call_tool("health_check")

# 2. Discover content structure  
library = await session.call_tool("library_info")
folders = await session.call_tool("folder_list")

# 3. Search and analyze
items = await session.call_tool("item_search", {"keyword": "design", "limit": 10})
image_data = await session.call_tool("image_base64", {"item_id": "abc123", "use_thumbnail": true})

📁 Project Structure

eagle-mcp-server/
├── main.py                 # Main MCP server implementation
├── run.bat                 # Server startup script (Windows)
├── eagle_client.py         # Eagle API client
├── config.py              # Configuration management
├── handlers/              # Tool handlers
│   ├── base.py            # Base handler class
│   ├── folder.py          # Folder operations (6 tools)
│   ├── item.py            # Item operations (6 tools)
│   ├── library.py         # Library operations (1 tool)
│   ├── image.py           # Image processing (4 tools)
│   └── direct_api.py      # Direct API access (17 tools)
├── utils/                 # Utility functions
│   ├── __init__.py
│   └── encoding.py        # Text encoding utilities
├── schemas/               # Pydantic schemas
├── tests/                 # Unit tests
├── debug/                 # Debug scripts
├── docs/                  # Documentation
└── scripts/               # Setup scripts

🧪 Testing

Run the test suite:

uv run python -m pytest tests/

Run basic functionality test:

# Basic health check
uv run python -c "from eagle_client import EagleClient; import asyncio; asyncio.run(EagleClient().health_check())"

# Test with Direct API tools enabled
EXPOSE_DIRECT_API_TOOLS=true uv run python debug/simple_test.py

# Run comprehensive test
uv run python test_v3.py

🐛 Troubleshooting

Common Issues

1. Connection refused: Ensure Eagle App is running on the configured port (default: 41595)
2. Module not found: Check Python path and virtual environment activation
3. Permission denied: Verify file permissions on startup scripts
4. Japanese text issues: Ensure UTF-8 encoding is properly configured
5. Direct API tools not visible: Set EXPOSE_DIRECT_API_TOOLS=true in your environment

See for detailed solutions.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Development Setup

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Install development dependencies: uv sync --extra dev
4. Make your changes
5. Run tests: uv run python -m pytest
6. Commit your changes (git commit -m 'Add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the file for details.

🔗 Related Links

• Model Context Protocol
• Eagle App
• MCP Python SDK

📞 Support

If you encounter any issues or have questions:

1. Check the
2. Search existing issues
3. Create a new issue

Note: This project requires Eagle App to be installed and running. Eagle App is a powerful digital asset management application available at eagle.cool.