Skip to main content
Glama

ojs-mcp

tests PyPI License: MIT

An MCP server for the authenticated REST API of Open Journal Systems (OJS 3.5/3.6). Connected to an MCP client (Claude Desktop, Claude Code, and others), it gives the model access to a journal's submissions, reviews, issues, and editorial statistics — and, with writes explicitly enabled, also to making editorial decisions, publishing, and editing metadata.

Verified against a live OJS 3.5

Every tool has been exercised end-to-end against a real OJS 3.5.0-5 instance — the sixteen read tools, the ojs_request escape hatch, and all five write tools. The write tools were checked by reading back the state OJS actually ended up in, not by trusting the status code: an announcement created, publication metadata edited, a submission carried from the submission stage to production by two editorial decisions, then published and unpublished again.

That instance is reproducible. demo/ holds the Docker stack, the fictional seed content, and the two scripts that drive this server against it as a real MCP client — check_api.py for the read tools, check_writes.py for the write tools.

Three things have not been exercised against a live server, and still rest on what the PKP source (pkp-lib, pkp/ojs) says rather than on observed behavior: login/password authentication (OJS_USERNAME/OJS_PASSWORD), network mode (OJS_MCP_TRANSPORT=http), and OJS 3.6 — only 3.5 has been tested. The unit test suite likewise runs entirely against stubbed HTTP responses (via respx).

Writes change real journal data, which is why OJS_ALLOW_WRITES=1 is off by default. Verify each tool's effect on a test journal before pointing it at production.

Related MCP server: zotero-mcp-server

Quick start

OJS_BASE_URL=https://journals.your-university.edu OJS_API_TOKEN=your-token uvx ojs-mcp

No separate install step needed — uv downloads and runs the package on first launch. In practice your MCP client calls this command for you, using the configuration format from the section below.

Before you start — this won't work without two things

The OJS REST API has no anonymous read access. For the server to be able to connect at all, both of these must be true on the OJS instance side:

  1. api_key_secret set in config.inc.php — without it, API tokens don't work at all (OJS responds with a 500 error to every request that carries a token). This must be done by the OJS server administrator; it can't be worked around from the outside.

  2. An account with a role in the specific journal — merely having an OJS account is not enough. Almost every API endpoint requires some role (manager, editor, reviewer...); an account with no role in the given journal gets denied (401) on almost every call.

A third condition applies to instances served by Apache — including the official pkpofficial/ojs Docker images: the web server must forward the Authorization header to PHP. Apache does not do that on its own, and when it doesn't, OJS answers 401 to every request carrying a token, with a response indistinguishable from an anonymous one. The one-line fix, and how to tell this case apart from a genuine permission problem, are in the authentication documentation.

Without these conditions the server will start, but every tool that reaches into OJS will return an authentication error. Details, including the login/password alternative and its limitations, are in docs/authentication.md.

Getting a token

A logged-in user generates an API token in their own OJS profile: User Profile → API Key (only available once the instance administrator has set api_key_secret — see above). The token acts with that account's permissions, so its scope is whatever roles that account holds in the given journal.

Example MCP client configuration

{
  "mcpServers": {
    "ojs": {
      "command": "uvx",
      "args": ["ojs-mcp"],
      "env": {
        "OJS_BASE_URL": "https://journals.your-university.edu",
        "OJS_JOURNAL": "my-journal",
        "OJS_API_TOKEN": "paste-your-ojs-profile-token-here"
      }
    }
  }
}

OJS_JOURNAL is optional — leave it out if the instance serves several journals and you'd rather pick one with the journal parameter on each call.

Where to actually paste this configuration

In Claude Desktop: Settings → Developer → Edit Config opens (and, on first use, creates) the claude_desktop_config.json file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Paste the snippet above under the mcpServers key — if the file already has other servers configured, add the "ojs" key alongside them, don't overwrite the whole file — save and restart Claude Desktop. Other desktop MCP clients have their own place for this configuration (e.g. Claude Code reads it via claude mcp add or from an .mcp.json file) — check their documentation; the shape of the env section above is the same across all of them.

This step disappears entirely when installing from the MCPB bundle (see below) — there, the instance address, journal, and token are filled in through a form in the client's UI, with no manual JSON editing at all. That's a good reason to reach for the bundle instead of uvx if editing a configuration file by hand isn't your thing.

Environment variables (summary)

Variable

Required

Description

OJS_BASE_URL

yes

The OJS instance address, exactly as it works in the browser.

OJS_JOURNAL

no

The journal shortcut — skips the journal parameter on every call.

OJS_API_TOKEN

no*

The token from a user's profile. Takes precedence over login/password.

OJS_USERNAME / OJS_PASSWORD

no*

Form-based login — won't work with reCAPTCHA/ALTCHA.

OJS_ALLOW_WRITES

no

1 exposes the tools that modify journal data (hidden by default).

* — either OJS_API_TOKEN or the OJS_USERNAME/OJS_PASSWORD pair is required (in stdio mode). The full list, including the network-mode variables (OJS_MCP_TRANSPORT and others), is in docs/configuration.md.

Alternative to uvx: the MCPB bundle

For desktop MCP clients that support the MCP Bundle (.mcpb) format — the installer file is attached to every release under Releases. Installation happens through the client's UI, configuration through a form instead of manual JSON editing; no Python or uv installation required — the bundle pulls its own dependencies on first run.

Documentation

Full documentation (installation, configuration, authentication, tool list, multi-tenant hosting): https://mpasternak.github.io/ojs-mcp/

License

MIT. See LICENSE.

Available Tools

17 tools
editorial_statsB

Aggregate editorial statistics for a journal (submission count, decisions, time to first decision, etc.) as a list of key/value pairs.

Dates date_from/date_to in YYYY-MM-DD format narrow the period; without them OJS computes statistics from the journal's inception.

Inputs: date_to, journal, date_from.

get_current_issueA

Fetch the journal's current issue (the one featured on the home page).

Returns issue: None if the journal does not yet have a current issue set.

Inputs: journal.

get_issueB

Fetch one issue of a journal by its ID.

Inputs: issue (required), journal.

get_publicationA

Fetch one version (publication) of a submission — full details.

A submission may have several versions (successive revisions after review) — find the publication ID in the result of get_submission. Unlike the trimmed list, this also returns the abstract, the full author list, keywords, the DOI, the page/ article number, and galleys — this version's ready-made files (PDF, HTML, etc.) with public links.

Inputs: submission (required), publication (required), journal.

get_submissionA

Fetch the details of one submission (article) by its ID.

Includes a trimmed list of its publications (versions). The full content of one version is returned by get_publication, and review rounds by get_submission_reviews.

Inputs: submission (required), journal.

get_submission_reviewsA

Fetch the review rounds and reviewer assignments for a submission.

Returns review_rounds (this submission's successive rounds) and review_assignments (who is reviewing, at which stage, with what result).

Inputs: submission (required), journal.

list_doisC

Find the DOIs registered for a journal.

status: unregistered, submitted, registered, error, stale.

Inputs: limit, status, journal.

list_issuesA

Find a journal's issues.

published_only=True restricts to already-published issues, False to those still being prepared; omitting it returns both kinds. sort_by: datePublished, lastModified, seq, publishedIssues, unpublishedIssues, shelf. OJS decides the sort direction itself for each of these values — it cannot be reversed here.

Inputs: limit, phrase, journal, sort_by, +1 more.

list_journalsA

List the journals visible to the current credentials.

Returns a list of {"path", "name"} objects. path is the value to pass as the journal parameter in the other tools.

Inputs: no named parameters.

list_reviewersB

Find a journal's reviewers together with their review statistics.

status: active (default), disabled, all. Returns, among others, the count of active/completed/declined reviews, the average review completion time in days, and the reviewer's rating.

Inputs: limit, phrase, status, journal.

list_sectionsB

Find a journal's sections, e.g. "Articles", "Reviews".

active_only=True skips disabled sections; omitting it returns all of them.

Inputs: limit, phrase, journal, active_only.

list_submission_filesA

Fetch the list of files attached to a submission (all stages).

Every file has file_stage_name alongside the numeric stage code, e.g. review_file, copyedit, final, body_text.

Inputs: submission (required), limit, journal.

ojs_requestA

Call any OJS REST API endpoint outside the ready-made tools.

path is relative to api/v1, e.g. 'submissions/12/files'. The ojs://endpoints resource returns the list of endpoints. journal="index" reaches site-level endpoints. Without OJS_ALLOW_WRITES, only read requests (GET/HEAD) are allowed. With the flag — this tool does NOT enforce the field list from edit_publication_metadata; the only write safeguard here is the OJS_ALLOW_WRITES flag itself.

Inputs: path (required), body, method, params, +1 more.

publication_statsA

Publication view statistics — a ranking or a time series.

timeline=False (default): a ranking of publications by view count. timeline=True: the sum of views over time; interval: day or month. Dates date_from/date_to in YYYY-MM-DD format.

Inputs: limit, date_to, journal, interval, +2 more.

search_submissionsB

Find submissions (articles) in a journal.

status: queued, published, declined, scheduled. stage: submission, external_review, editing, production. section: a list of section IDs (from list_sections). inactive_days: only submissions inactive for N days. sort_by: datePublished, dateSubmitted, lastActivity, lastModified, sequence, title. descending=True sorts descending (default). Dates in YYYY-MM-DD format. The date filter only applies to already-fetched pages of the result — see the date_filtering_incomplete field in the response.

Inputs: limit, stage, phrase, status, +7 more.

search_usersC

Find a journal's users by name/email, status, and role.

status: active (default), disabled, all. role: site_admin, manager, sub_editor, reviewer, assistant, author, reader, subscription_manager.

Inputs: role, limit, phrase, status, +1 more.

whoamiB

Check whether the current credentials work, and who you are.

API token: OJS has no identity endpoint for a token — this tool reports ONLY whether authentication works at all, not who the user is (identity in the response is then None).

Login and password: identity carries the logged-in user's real data (id, username, fullName, roles, role_names).

Inputs: journal.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 17 tools

    Disambiguation5/5

    Each tool targets a distinct resource or action: journals, submissions, publications, files, reviews, issues, sections, users, reviewers, stats, and DOIs are clearly separated. The only potential overlap (get_submission vs get_publication) is well-defined as different granularities of the same object.

    Naming Consistency5/5

    Tool names follow a consistent snake_case verb_noun pattern: list_*, get_*, search_* for actions, with the exceptions of whoami (a standard idiom) and the two *_stats nouns, which are still predictable. No mixed conventions.

    Tool Count5/5

    17 tools is appropriate for a complex domain like OJS, covering journal management, submissions, publications, files, reviews, issues, users, reviewers, statistics, and DOIs. Each tool earns its place, and the set is neither too thin nor bloated.

    Completeness3/5

    The read side is thorough (listing, fetching, searching, stats), but there are no dedicated create/update/delete tools for submissions, issues, sections, or users. Write operations are only possible via the generic ojs_request tool, which requires a special flag and is not a first-class tool, leaving a notable gap for full lifecycle management.

    Maintenance

    ActivityStale
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      D
      maintenance
      Exposes the OpenProject REST API as MCP tools for project management, including creating and managing projects, work packages, relations, attachments, users, notifications, watchers, boards, and reference data.
      37
      -
    • A
      license
      A
      quality
      B
      maintenance
      MCP server for the OpenAlex scholarly graph API, enabling searches for authors, works, institutions, sources, and citation data. Supports optional query logging with hash-chained receipts.
      8
      1
      MIT