<!-- 🇬🇧 English | 🇫🇷 Français -->

hal-mcp

An MCP (Model Context Protocol) server for HAL, the French national open archive (Hyper Articles en Ligne). It lets an AI assistant — Claude, or any MCP-compatible client — query HAL: search publications, compute statistics, export citations, and track a researcher's output.

No API key required. It goes beyond simple search with facets (aggregate statistics), author tracking by IdHAL, and native bibliographic export.

Features (6 tools)

Tool	Description
search_publications	Search with human-friendly filters: year range, document type, open access, full-text availability, sorting.
get_publication	Full record for a single document by its HAL identifier.
export_citations	Export to BibTeX / EndNote / CSV / TEI (via HAL's native wt parameter).
get_publication_stats	Aggregate counts (by year, type, keyword, author) using Solr facets.
get_author_production	Complete output of a researcher by IdHAL, with most frequent co-authors optionally.
search_structures	Search for laboratories / research structures.

Requirements

• Python 3.10 or newer
• The mcp SDK, version 1.x (see the important note below)

⚠️ Important — mcp SDK version This server uses FastMCP, which was removed in mcp v2.0.0. The project therefore pins mcp>=1.2.0,<2.0.0. If you see a FastMCP import error at startup, v2 was installed by mistake: reinstall with pip install "mcp<2.0.0".

Installation

git clone https://github.com/Arpany-Tech/hal-mcp
cd hal-mcp
pip install -e .

Verify it works

1. Check the server starts

python -m hal_mcp.server

The cursor hangs with no output: this is expected. The server is running and waiting for MCP messages on standard input. Press Ctrl+C to stop it. (If you get an error instead, see the mcp SDK note above.)

2. Interactive testing with MCP Inspector

The official tool to explore an MCP server without a full client:

npx @modelcontextprotocol/inspector python -m hal_mcp.server

Open the printed URL, click Connect, then List Tools: the 6 tools appear. You can call each one by hand and inspect the responses.

3. Test the API layer directly (no MCP)

python3 - << 'PY'
import asyncio
from hal_mcp import client

async def main():
    res = await client.search_publications(
        "artificial intelligence", year_from=2023,
        open_access_only=True, rows=3,
    )
    print("Total:", res["total"])
    for d in res["documents"]:
        print("-", d.get("label_s"))

asyncio.run(main())
PY

Connect to Claude Desktop

In claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "hal": {
      "command": "python",
      "args": ["-m", "hal_mcp.server"]
    }
  }
}

Fully restart Claude Desktop. The HAL tools appear in the tools indicator of the message box.

Tip: if Claude Desktop can't find python, use the full path to your interpreter (e.g. C:\\Python313\\python.exe on Windows) instead of "python" in command.

Example questions

• "Find open-access articles on federated learning since 2023."
• "Give me the output of the researcher with IdHAL dominique-lesselier, with co-authors."
• "What is the year-by-year breakdown of deep learning publications?"
• "Export the 10 most recent publications on transformers to BibTeX."
• "Which laboratories work on quantum physics?"

How it works

HAL exposes a search API built on Apache Solr, queryable over HTTP with no authentication. This server translates human-friendly parameters (year_from, doc_type, open_access_only...) into Solr syntax (fq, facet, wt...), so the agent gets a simple interface while still benefiting from Solr's power (filters, facets, exports).

• HAL API documentation: https://api.archives-ouvertes.fr/docs/search
• Structure reference: https://api.archives-ouvertes.fr/docs/ref/resource/structure

Architecture

src/hal_mcp/
├── server.py    # declares the 6 MCP tools (FastMCP)
├── client.py    # calls to HAL's Solr API (httpx)
└── fields.py    # constants: Solr fields, document types

The client.py layer has no MCP dependency: it can be tested in isolation.

Development

Run the tests:

pip install pytest pytest-asyncio
pytest                    # all tests
pytest -m "not network"   # unit tests only (offline, fast)
pytest -m network         # integration tests that call HAL

Roadmap

• get_structure_output — output of a given laboratory.
• Pivot facets (cross type × full-text, year × type).
• Range facets (facet.range) for time-series/evolution charts.
• Collection / portal filtering exposed as a parameter.
• HTTP transport for Claude.ai (connector) and ChatGPT (developer mode).

License

MIT — see the LICENSE file.

Disclaimer

Independent project, not affiliated with the CCSD (which operates HAL). Metadata comes from HAL's public API. Please respect HAL's terms of use and the license of each individual publication.