OpenAlex Author Disambiguation MCP Server

OpenAlex Author Disambiguation MCP Server

A streamlined Model Context Protocol (MCP) server for author disambiguation and academic research using the OpenAlex.org API. Specifically designed for AI agents with optimized data structures and enhanced functionality.

🎯 Key Features

🔍 **Core Capabilities**

• Advanced Author Disambiguation: Handles complex career transitions and name variations
• Institution Resolution: Current and past affiliations with transition tracking
• Academic Work Retrieval: Journal articles, letters, and research papers
• Citation Analysis: H-index, citation counts, and impact metrics
• ORCID Integration: Highest accuracy matching with ORCID identifiers

🚀 **AI Agent Optimized**

• Streamlined Data: Focused on essential information for disambiguation
• Fast Processing: Optimized data structures for rapid analysis
• Smart Filtering: Enhanced filtering options for targeted queries
• Clean Output: Structured responses optimized for AI reasoning

🤖 **Agent Integration**

• Multiple Candidates: Ranked results for automated decision-making
• Structured Responses: Clean, parseable output optimized for LLMs
• Error Handling: Graceful degradation with informative messages
• Enhanced Filtering: Journal-only, citation thresholds, and temporal filters

🏛️ **Professional Grade**

• MCP Best Practices: Built with FastMCP following official guidelines
• Tool Annotations: Proper MCP tool annotations for optimal client integration
• Resource Management: Efficient HTTP client management and cleanup
• Rate Limiting: Respectful API usage with proper delays

🚀 Quick Start

Prerequisites

• Python 3.10 or higher
• MCP-compatible client (e.g., Claude Desktop)
• Email address (for OpenAlex API courtesy)

Installation

For detailed installation instructions, see INSTALL.md.

1. Clone the repository:

   git clone https://github.com/drAbreu/alex-mcp.git
   cd alex-mcp
   

2. Create a virtual environment:

   python3 -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

3. Install the package:

   pip install -e .
   

4. Configure environment:

   export OPENALEX_MAILTO=your-email@domain.com
   

5. Run the server:

   ./run_alex_mcp.sh
   # Or, if installed as a CLI tool:
   alex-mcp
   

⚙️ MCP Configuration

Claude Desktop Configuration

Add to your Claude Desktop configuration file:

{
  "mcpServers": {
    "alex-mcp": {
      "command": "/path/to/alex-mcp/run_alex_mcp.sh",
      "env": {
        "OPENALEX_MAILTO": "your-email@domain.com"
      }
    }
  }
}

Replace /path/to/alex-mcp with the actual path to the repository on your system.

🤖 Using with AI Agents

OpenAI Agents Integration

You can load this MCP server in your OpenAI agent workflow using the `agents.mcp.MCPServerStdio` interface:

from agents.mcp import MCPServerStdio

async with MCPServerStdio(
    name="OpenAlex MCP For Author disambiguation and works",
    cache_tools_list=True,
    params={
        "command": "uvx",
        "args": [
            "--from", "git+https://github.com/drAbreu/alex-mcp.git@4.1.0",
            "alex-mcp"
        ],
        "env": {
            "OPENALEX_MAILTO": "your-email@domain.com"
        }
    },
    client_session_timeout_seconds=10
) as alex_mcp:
    await alex_mcp.connect()
    tools = await alex_mcp.list_tools()
    print(f"Available tools: {[tool.name for tool in tools]}")

Academic Research Agent Integration

This MCP server is specifically optimized for academic research workflows:

# Optimized for academic research workflows
from alex_agent import run_author_research

# Enhanced functionality with streamlined data
result = await run_author_research(
    "Find J. Abreu at EMBO with recent publications"
)

# Clean, structured output for AI processing
print(f"Success: {result['workflow_metadata']['success']}")
print(f"Quality: {result['research_result']['metadata']['result_analysis']['quality_score']}/100")

Direct Launch with uvx

# Standard launch
uvx --from git+https://github.com/drAbreu/alex-mcp.git@4.1.0 alex-mcp

# With environment variables
OPEN