ojs-mcp
This server provides an MCP interface to the Open Journal Systems (OJS) REST API, enabling management of journal content, users, reviews, and statistics, with optional write access.
List and identify journals available to the current credentials.
Verify authentication and (with login/password) identify the current user.
Search and retrieve submissions (articles) with filters by status, stage, section, date, inactivity, and sorting; fetch full submission details and publication versions (including abstract, authors, keywords, DOI, galleys).
List files attached to submissions across all workflow stages.
Retrieve review rounds and reviewer assignments.
List, search, and fetch journal issues (current issue, published/unpublished) and sections.
Search users by name/email, status, and role; list reviewers with review statistics.
Get publication view statistics (rankings or time series) and aggregate editorial statistics (submissions, decisions, time-to-first-decision).
Search and list DOI records by registration status.
Issue raw REST API calls to any OJS endpoint (read-only by default; write enabled via OJS_ALLOW_WRITES=1).
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ojs-mcp show me the latest submissions awaiting review"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
ojs-mcp
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-mcpNo 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:
api_key_secretset inconfig.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.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.jsonWindows:
%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 |
| yes | The OJS instance address, exactly as it works in the browser. |
| no | The journal shortcut — skips the |
| no* | The token from a user's profile. Takes precedence over login/password. |
| no* | Form-based login — won't work with reCAPTCHA/ALTCHA. |
| no |
|
* — 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 toolseditorial_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
Scored across 17 tools
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.
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.
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.
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
Related MCP Connectors
OSF (Open Science Framework, by the Center for Open Science) MCP. Keyless public-data API…
Unofficial OpenAlex MCP — wraps the OpenAlex API (scholarly works, free, no auth)
MCP server for Altmetric APIs - track research attention across news, policy, social media, and more
WordPress plugin exposing 60 MCP tools via OAuth 2.1: posts, pages, media, users, comments and SEO.
Related MCP Servers
- FlicenseAqualityDmaintenanceExposes 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-
- FlicenseAqualityDmaintenanceAn MCP server for the Zotero Web API v3 that lets you search, read, and write items, collections, tags, and notes in a Zotero library, supporting literature-review workflows.9-
- AlicenseAqualityBmaintenanceMCP 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.81MIT
- AlicenseAqualityBmaintenanceExposes KCI and OAK Korean bibliographic services as MCP tools for searching, harvesting, and retrieving articles, references, and journal metrics.91MIT