philosophy-mcp

An MCP server for philosophy texts — both current scholarship and the canon. It folds these into one keyless server:

• PhilPapers / PhilArchive — the philosophy preprint archive (the field's closest analog to arXiv): search papers, read abstracts, browse recent submissions, pull full text.

• Books, classics & reference — public-domain originals and translations (Project Gutenberg, Internet Archive, Wikisource), open-access academic books (DOAB), modern editions (Open Library), and the Stanford Encyclopedia of Philosophy — plus a generic fetch_text for any other source (Zeno.org, marxists.org, Standard Ebooks, …).

• Local documents — open a large local PDF or text file and work it without loading the whole thing into context: outline, in-file search, and paged reading.

No API key required. Everything runs against keyless public endpoints.

Renamed and expanded from philpapers-mcp (which covered only the PhilPapers tools). The philpapers-mcp binary name still works as an alias.

Tools

Philosophy scholarship (PhilPapers / PhilArchive)

PhilArchive is the open-access archive built on the PhilPapers database, so a record id such as BROTNO-9 resolves on both philarchive.org and philpapers.org.

Books, classics & reference

All text-returning tools (get_fulltext, the get_*_text readers, get_sep_entry, fetch_text) return one window — max_chars characters (default 15000) starting at offset (default 0). When the body is longer, the footer reports the next offset to continue from, so you page through a long work a window at a time instead of dumping it whole (and re-dumping from the start to read further). Each fetched/extracted body is cached, so paging doesn't re-download or re-parse the source.

Local documents

These read a large local file the way you'd skim a thick book — get an outline, jump to the relevant pages by searching, then read a chunk at a time — so only the parts that matter reach the context. Only files under $HOME are readable by default; add more roots via PHILOSOPHY_DOC_ROOTS.

Example

search_papers with { "query": "phenomenal consciousness higher-order", "open_access_only": true, "limit": 2 }:

Found 1,806 match(es) in PhilPapers/PhilArchive; showing 2 (open-access only).

1. The HOROR theory of phenomenal consciousness (2014)
   id: BROTNO-9
   authors: Richard Brown
   philarchive: https://philarchive.org/rec/BROTNO-9
   pdf: https://philpapers.org/archive/BROTNO-9.pdf

Then get_fulltext with { "id": "BROTNO-9" } returns the paper's extracted full text.

For the canon: search_gutenberg with { "query": "kant critique", "languages": "en" } returns book ids, and get_gutenberg_text with { "book_id": 4280 } reads The Critique of Pure Reason directly; search_sep → get_sep_entry reads an encyclopedia entry; fetch_text pulls readable text from German originals on Zeno.org or translations on marxists.org.

20th-century authors still in copyright (Heidegger, Adorno, Gadamer, Habermas) won't have free full texts here — you'll get metadata, SEP coverage, and read/borrow links.

Setup

Run straight with npx (no clone, once published):

npx -y philosophy-mcp

Or from source:

git clone https://github.com/sea9401/philosophy-mcp
cd philosophy-mcp
npm install   # the `prepare` hook builds dist/ automatically

Updating

dist/ is committed, so an existing source checkout updates with a plain pull — no build step:

cd philosophy-mcp
git pull

Then restart the MCP server (reconnect in Claude Code, or restart Claude Desktop) so it loads the new build. Maintainers: rebuild and commit dist/ whenever you change src/ — CI fails if the two drift.

Register with Claude Code

# via npx (no clone)
claude mcp add philosophy -- npx -y philosophy-mcp

# from a local build
claude mcp add philosophy -- node /absolute/path/to/dist/index.js

# optional: identify yourself to OpenAlex's "polite pool" for better rate limits
claude mcp add philosophy -e OPENALEX_MAILTO=you@example.com -- npx -y philosophy-mcp

Then /mcp inside Claude Code lists philosophy with its tools.

Register with Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "philosophy": {
      "command": "node",
      "args": ["/home/sea9401/philpapers-mcp/dist/index.js"],
      "env": { "OPENALEX_MAILTO": "you@example.com" }
    }
  }
}

Environment variables

Smoke test

npm test   # builds, then runs smoke-test.mjs

smoke-test.mjs spawns the server over stdio, performs the MCP handshake, and verifies every expected tool is registered — no network calls, so it's the regression guard CI runs. (The older node test-client.mjs additionally exercises a couple of live PhilPapers calls.)

Notes & limits

• The book/reference tools are keyless and read-only. Search tools return compact lists; the get_* / fetch_text tools return one max_chars window from offset and report the next offset to continue — page through long works instead of pulling them whole.

• Gutendex (the Project Gutenberg API host) is frequently overloaded; search_gutenberg probes it briefly and falls back to gutenberg.org's OPDS feed. get_gutenberg_text reads the text directly from gutenberg.org, so it works even when Gutendex is down.

• SEP has no keyword API (its on-site search is JavaScript-driven), so search_sep matches against the published entry index (contents.html) — i.e. title/topic matching.

• list_recent filters on the OAI datestamp, returns only the first OAI page, and not every record has an open-access PDF — get_paper reports availability; fetch_pdf fails clearly.

Publishing (maintainers)

CI (.github/workflows/ci.yml) builds on Node 18/20/22 for every push and PR.

To publish a new version to npm:

1. Add a repo secret NPM_TOKEN (an npm Automation access token) under Settings → Secrets and variables → Actions.

2. Bump the version and tag: npm version patch && git push --follow-tags.

3. Cut a GitHub Release — .github/workflows/publish.yml runs npm publish automatically.

Or publish manually: npm login then npm publish --access public.

License

MIT