jstage-mcp

A FastMCP stdio server exposing the J-STAGE WebAPI as four tools for use with Claude Desktop.

Tools

Tool	Purpose
jstage_search_articles	Full-text / author / title / journal search across J-STAGE articles
jstage_list_issues	Volume & issue spine for a known title, ISSN, or cdjournal
jstage_search_journals	Find journals by title / ISSN / publisher (see Limitations)
jstage_get_article_by_doi	Resolve a J-STAGE DOI to its full article record

All tools return JSON with bilingual (English / Japanese) titles, authors, and journal names where J-STAGE provides them. Every response includes a powered_by field per the JST attribution requirement.

Install (Windows, alongside CiNii / OpenAlex / Semantic Scholar)

The server is single-file and has only three runtime dependencies. Use a dedicated virtual environment so it doesn't collide with other MCP stacks.

# from the directory containing server.py
py -3.11 -m venv .venv
.venv\Scripts\activate
pip install -e .

Verify the server boots:

.venv\Scripts\python.exe server.py --help

Claude Desktop configuration

Add an entry to %APPDATA%\Claude\claude_desktop_config.json under mcpServers. Adjust the absolute paths to match your install location.

{
  "mcpServers": {
    "jstage": {
      "command": "C:\\path\\to\\jstage-mcp\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\jstage-mcp\\server.py"]
    }
  }
}

Restart Claude Desktop. The four tools should appear under "jstage" in the tool list.

Rate limiting

The server enforces a one-second minimum interval between outbound requests in line with JST's prohibition on bulk downloads. The limit is per-process; if you run multiple Claude Desktop sessions concurrently you may exceed it, so don't.

Limitations

• jstage_search_journals runs against a fallback. J-STAGE announced a journal-search endpoint (service=4) on 26 March 2026, but the public API currently rejects that service code with ERR_004. The tool probes service=4 first and, on failure, falls back to service=2 (volume search) with results deduplicated by journal. When JST activates service=4, the tool will use it natively without a contract change.
• jstage_get_article_by_doi requires J-STAGE-issued DOIs. The WebAPI does not expose a doi= query parameter. The tool decomposes DOIs that follow J-STAGE's pattern (10.<registrant>/<cdjournal>.<vol>.<no>_<page>) into cdjournal+vol and matches the result against the response. For DOIs outside that pattern the tool returns the doi.org resolution URL with a note.
• Commercial use requires registration. Per the JST Terms of Use, commercial use needs an application form sent to contact@jstage.jst.go.jp. Research and teaching use does not.

API notes

Endpoint: https://api.jstage.jst.go.jp/searchapi/do

Service codes used:

• service=2 — Volumes/issues
• service=3 — Article search
• service=4 — Journal search (documented, not yet live)

Valid article-search query parameters confirmed against the live API: material, article, author, affil, keyword, abst, text, issn, cdjournal, vol, no, pubyearfrom, pubyearto, start, count.

Attribution

Powered by J-STAGE

This string is included in every tool response.

Citation

If this software supports your research, please cite it. See CITATION.cff, or use the "Cite this repository" button on GitHub.

License

MIT © 2026 Christopher Gerteis.

This license covers the server code only. It grants no rights over J-STAGE content or the J-STAGE WebAPI, which remain governed by JST's Terms of Use.

Disclaimer

A research tool, maintained on a best-effort basis and provided "as is", without warranty. Not affiliated with or endorsed by the Japan Science and Technology Agency. JST does not provide support for the WebAPI.

Author

Dr Christopher Gerteis, SOAS University of London.