MTMT-MCP

A simple Model Context Protocol (MCP) server for the Hungarian Science Bibliography (MTMT), built with Python and FastMCP.

MTMT-MCP lets MCP clients search the public MTMT catalogue and retrieve bibliographic records, authors, journals, institutions, conferences, grants, and publishers. It is read-only and does not require MTMT credentials for public records.

Features

• Search publications by title, author, journal, external identifier, year, university, and department.
• Resolve universities and organizational units to stable MTMT institution IDs.
• Resolve author profiles before listing a specific researcher's publications.
• Retrieve MTMT's official author summary metrics and both h-index variants.
• Fetch one publication or batch-fetch up to 20 known MTMT IDs.
• Traverse explicit incoming and outgoing MTMT citation links.
• Run advanced searches using native MTMT conditions.
• Retrieve public records by MTMT ID.
• Control response size with MTMT field selection.
• Use English or Hungarian response labels.
• Connect over MCP's standard input/output transport.

Requirements

• Python 3.11 or newer
• An MCP-compatible client

Installation

Install the latest release from PyPI:

python -m pip install --upgrade mtmt-mcp

Run the installed server:

mtmt-mcp

You can also run the PyPI package in an isolated environment without installing it permanently:

uvx mtmt-mcp

Install from source

For development, clone the repository and install it in a virtual environment:

git clone https://github.com/attilaimre99/MTMT-MCP.git
cd MTMT-MCP
python -m venv .venv

On Linux or macOS:

source .venv/bin/activate
pip install -e .

On Windows PowerShell:

.venv\Scripts\Activate.ps1
pip install -e .

Run the server:

mtmt-mcp

You can also run it without installing the command-line entry point:

python -m mtmt_mcp.server

Expose the server through ngrok

The commands above use MCP's local stdio transport. To connect from a remote MCP client, start FastMCP's HTTP transport and expose its port through ngrok.

In the first terminal, start the HTTP server on port 8000:

uv run python -c 'from mtmt_mcp.server import mcp; mcp.run(transport="http", host="127.0.0.1", port=8000)'

If the project environment is already activated, python can be used instead of uv run python. The server should report that it is listening at http://127.0.0.1:8000/mcp.

In a second terminal, start the tunnel. Use a reserved ngrok domain when one is available:

ngrok http --url=your-subdomain.ngrok-free.dev 8000

Without a reserved domain, let ngrok assign a temporary URL:

ngrok http 8000

Configure the remote MCP client with the public URL shown by ngrok and append /mcp:

https://your-subdomain.ngrok-free.dev/mcp

Both terminal processes must remain running. Restarting a tunnel without a reserved domain usually changes its public URL.

MCP client configuration

After installing from PyPI, add the server command to the MCP client configuration:

{
  "mcpServers": {
    "mtmt": {
      "command": "mtmt-mcp"
    }
  }
}

Alternatively, let uvx download and run the latest PyPI release in an isolated environment:

{
  "mcpServers": {
    "mtmt": {
      "command": "uvx",
      "args": ["mtmt-mcp"]
    }
  }
}

For an editable source checkout, replace /absolute/path/to/MTMT-MCP with the local repository path:

{
  "mcpServers": {
    "mtmt": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/MTMT-MCP",
        "run",
        "mtmt-mcp"
      ]
    }
  }
}

If uv is not installed, point the client directly at the virtual environment's Python:

{
  "mcpServers": {
    "mtmt": {
      "command": "/absolute/path/to/MTMT-MCP/.venv/bin/python",
      "args": ["-m", "mtmt_mcp.server"]
    }
  }
}

On Windows, the command path ends in .venv\\Scripts\\python.exe.

Available tools

search_publications

Search publications by any combination of title, author name, earliest year, and latest year, journal, exact external identifier such as a DOI or ISBN, university MTMT ID, or department MTMT ID. This is the primary tool for literature discovery. It returns compact metadata, recorded institutional affiliations, and paging information; an agent can request abstracts only when needed.

Example request:

Find MTMT publications with "machine learning" in the title, published since 2022.

search_institutes

Resolve a university, faculty, clinic, institute, department, or research-unit name to a stable MTMT institution ID before filtering publications. Results include organizational type, immediate parents, child count, active dates, and names in both Hungarian and English.

For reliable department filtering, use a two-step workflow:

1. Resolve the university and retain its MTMT ID.
2. Resolve the department with within_university_mtid set to that university ID.
3. Pass the selected IDs as university_mtid and department_mtid to search_publications.

University and department filters are hierarchy-aware: they include publications assigned to the selected organization or any organizational unit below it in MTMT. MTMT affiliation coverage depends on the institutions recorded on each authorship.

get_publication and get_publications

Retrieve detailed metadata for one known publication, or batch-fetch up to 20 MTMT IDs. The results include authorships, identifiers, publication type, journal or publisher, open-access metadata, and citation counts. Abstracts are optional to keep agent context manageable. The batch tool reports individual failures without discarding successful records.

search_authors and get_author_publications

First resolve a researcher's name to a stable MTMT author ID, then list publications linked to that exact profile. This workflow is preferable to name-only publication searches when authors have common names or several name variants.

get_author_metrics

Read the public MTMT "összesítő táblázat" for an identified author. The result includes the independent-citation and all-citation Hirsch indices, core scientific and overall publication/citation totals, selected author-profile counts, and an optional category breakdown. These are MTMT metrics—not estimates calculated from a capped search result. MTMT's table notes state that the h-index is based on all scientific publications and excludes citing dissertations and records classified as other publication types.

get_publication_connections

Return publications recorded by MTMT as citing a source (cited_by) or publications referenced from an MTMT citation record (references). Citation coverage depends on MTMT's curated records; this tool is not a semantic similarity search.

search_mtmt

Search any supported record collection using native MTMT query conditions. A condition has the form field;operator;value. Conditions can be combined with AND or OR.

resource_type: publication
conditions:
  - title;any;machine learning
  - publishedYear;ge;2022
sort:
  - publishedYear,desc
size: 10

Page numbers are one-based: use page: 1 for the first page.

Common operators include eq, ne, any, prefix, gt, ge, lt, le, in, isnull, and notnull. The fields and valid operators depend on the record type.

Supported collections are publication, author, journal, institute, conference, funding, and publisher.

get_mtmt_record

Retrieve one public record by its resource type and MTMT ID. Use include_fields to keep large records focused, for example:

resource_type: publication
mtid: 12345678
include_fields: title,publishedYear,authorships:1,identifiers

Configuration

The defaults work with the public MTMT service. These optional environment variables are available for development or self-hosted gateways:

MTMT API documentation

The official MTMT2 API documentation is available here:

MTMT2 API documentation (PDF)

MTMT also publishes the current list of query operators at m2.mtmt.hu/api-docs/query-ops.

The upstream API uses application/vnd.mtmt2-1.0+json, returns records inside a content property, and includes paging metadata for collection searches. MTMT may cap the total accessible result set; use narrow conditions and pagination for reliable calls.

Development

Install the development dependencies and run the checks:

pip install -e ".[dev]"
ruff check .
pytest

Pull requests and pushes to main run Ruff, the test suite on Python 3.11 through 3.13, and a package build. The release workflow runs when a GitHub release is published. It requires a v<project-version> tag, attaches the wheel and source distribution to the GitHub release, and publishes them to PyPI through trusted publishing.

Before the first release, create a pypi GitHub environment and configure a PyPI trusted publisher for this repository, the release.yml workflow, and that environment. Keep the versions in pyproject.toml and src/mtmt_mcp/__init__.py synchronized.

Create subsequent releases with the version-bump script:

uv run python scripts/bump_version.py patch --dry-run
uv run python scripts/bump_version.py patch

Replace patch with minor or major as needed. The script requires a clean local main that exactly matches origin/main. It updates both version declarations and uv.lock, runs Ruff and the test suite, commits and pushes the bump, creates and pushes the matching vX.Y.Z tag, and publishes a GitHub release. Publishing that release triggers the PyPI workflow.

License

Licensed under the Apache License 2.0.