pip install openalex-mcp

python --version   # needs 3.11 or higher
# Install if missing: https://python.org/downloads

# Windows
winget install astral-sh.uv

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

uvx openalex-mcp          # install and run — uv handles everything
uv tool upgrade openalex-mcp  # upgrade later

pip install openalex-mcp
which openalex-mcp    # macOS/Linux → /usr/local/bin/openalex-mcp
where openalex-mcp    # Windows    → C:\Users\YOU\AppData\...

git clone https://github.com/JOSETRA44/openalex-mcp.git
cd openalex-mcp
uv sync
cp .env.example .env   # edit .env with your key
uv run openalex-mcp    # run directly

{
  "mcpServers": {
    "openalex": {
      "command": "uvx",
      "args": ["openalex-mcp"],
      "env": {
        "OPENALEX_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

{
  "mcpServers": {
    "openalex": {
      "command": "uvx",
      "args": ["openalex-mcp"],
      "env": {
        "OPENALEX_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

{
  "mcpServers": {
    "openalex": {
      "command": "uv",
      "args": [
        "--directory", "/absolute/path/to/openalex-mcp",
        "run", "openalex-mcp"
      ],
      "env": {
        "OPENALEX_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

{
  "mcpServers": {
    "openalex": {
      "command": "uvx",
      "args": ["openalex-mcp"],
      "env": {
        "OPENALEX_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

{
  "servers": {
    "openalex": {
      "type": "stdio",
      "command": "uvx",
      "args": ["openalex-mcp"],
      "env": {
        "OPENALEX_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

{
  "mcpServers": {
    "openalex": {
      "command": "uvx",
      "args": ["openalex-mcp"],
      "env": {
        "OPENALEX_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

{
  "context_servers": {
    "openalex": {
      "command": {
        "path": "uvx",
        "args": ["openalex-mcp"],
        "env": {
          "OPENALEX_API_KEY": "YOUR_API_KEY_HERE"
        }
      }
    }
  }
}

mcpServers:
  - name: openalex
    command: uvx
    args:
      - openalex-mcp
    env:
      OPENALEX_API_KEY: "YOUR_API_KEY_HERE"

command: uvx
args:    ["openalex-mcp"]
env:     OPENALEX_API_KEY=YOUR_API_KEY_HERE

# Interactive
python setup_mcp.py

# Non-interactive — configure all detected clients
python setup_mcp.py --key YOUR_API_KEY_HERE --yes

# Preview without writing files
python setup_mcp.py --key YOUR_API_KEY_HERE --dry-run --yes

# Show detected clients only
python setup_mcp.py --list

pip install openalex-mcp        # or: uv tool install openalex-mcp
openalex --help                 # confirm it's on your PATH

openalex search-works "federated learning privacy" -f "publication_year:>2021,type:article" -s "cited_by_count:desc"
openalex get-work 10.1038/s41586-021-03819-2
openalex search-authors "Geoffrey Hinton"
openalex aggregate-works publication_year -f "institutions.id:I865918315" --json | jq '.groups[0]'

# Find recent papers on a topic
openalex_search_works(
    query="federated learning privacy",
    filters="publication_year:>2021,type:article",
    sort="cited_by_count:desc"
)

# Get full paper details by DOI
openalex_get_work("10.1038/s41586-021-03819-2")

# Find an author and get their profile
openalex_search_authors(query="Geoffrey Hinton")
openalex_get_author("A2208157607")

# Find an institution, then see its recent output
openalex_search_institutions(query="UNAM", country_code="MX")
openalex_search_works(
    filters="institutions.id:I865918315,publication_year:>2020",
    sort="cited_by_count:desc"
)

# Annual publication trend for a topic
openalex_aggregate_works(
    group_by="publication_year",
    filters="type:article",
    query="machine learning"
)

# Find open-access journals in a field
openalex_search_sources(
    query="bioinformatics",
    is_oa=True,
    source_type="journal"
)

npx @modelcontextprotocol/inspector uvx openalex-mcp

echo "" | OPENALEX_API_KEY=your_key uvx openalex-mcp
# Should start without errors, then exit when stdin closes

uv sync --group dev
uv run pytest tests/ -v
# Expected: 28 passed

openalex-mcp/
├── src/openalex_mcp/
│   ├── server.py           # FastMCP entry point (registers tools as MCP tools)
│   ├── cli.py              # `openalex` CLI entry point (calls the same tool functions)
│   ├── cli_output.py       # Human-readable table/detail rendering for the CLI
│   ├── config.py           # Env var configuration (pydantic-settings)
│   ├── client.py           # Async HTTP client + TTL cache + rate limiting
│   ├── exceptions.py       # Error hierarchy
│   ├── formatters.py       # Raw OpenAlex JSON → clean AI-friendly dicts
│   ├── tools/              # Core tool functions, shared by server.py and cli.py
│   └── resources/          # openalex://filter-reference static resource
├── openalex-researcher/    # Agent skill
│   ├── SKILL.md
│   └── references/         # Filter syntax, workflows, output reference
├── tests/                  # Unit tests (28 cases, no network required)
├── setup_mcp.py            # Automated config installer
├── .env.example            # Environment variable template
└── pyproject.toml          # Package definition