Set Up the OokCite MCP Server#

The OokCite MCP server gives LLMs the ability to validate, look up, format, and manage academic citations. It returns citation metadata only – not PDFs or full-text articles. Use it to prevent hallucinated references, format bibliographies, manage citation collections, and verify DOIs before submission.

Quick Start#

One command to install and configure:

npx @turtletech/ookcite-mcp setup

This auto-detects your MCP clients (Claude Desktop, Claude Code, Cursor, Codex) and writes the config for you. Connect an account for higher rate limits and collection tools without putting an API key in shell arguments or MCP config:

npx @turtletech/ookcite-mcp setup --connect

The command opens the TurtleTech dashboard and stores the issued key in the platform credential store. The MCP configuration contains only a credential reference. Use the device flow on a headless machine:

npx @turtletech/ookcite-mcp setup --connect --device

An existing API key remains supported:

npx @turtletech/ookcite-mcp setup --key YOUR_API_KEY

No API key required for basic usage (20 lookups/day). Sign up for more.

After changing MCP config, restart the client or reload its MCP servers. Many clients do not hot-reload environment-variable changes for already-running stdio servers.

Alternative Installation#

If you prefer not to use npx:

npm (recommended):

npm install -g @turtletech/ookcite-mcp

cargo-binstall (fastest, no Node.js):

cargo binstall ookcite-mcp

cargo install (from source):

cargo install ookcite-mcp

Pre-built binaries: Download from GitHub Releases for Linux, macOS, and Windows.

Configure Your MCP Client#

If you used setup, you are done. Otherwise, add to your MCP client config manually. OokCite uses the standard Model Context Protocol (MCP) over stdio. It works with any MCP-compatible client: Claude Desktop, Claude Code, Codex, OpenCode, Cursor, Windsurf, Qwen agents, Gemini, oh-my-posh, and others.

Generic MCP config (works everywhere)#

Most MCP clients accept a JSON config. Add OokCite:

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

With an API key:

{
  "mcpServers": {
    "ookcite": {
      "command": "ookcite-mcp",
      "env": {
        "OOKCITE_API_KEY": "your_key_here"
      }
    }
  }
}

Secure Credential Storage#

setup --connect uses the platform credential store by default. It refuses to replace an existing credential or named OokCite MCP configuration unless --replace-credential or --replace-config is supplied explicitly.

A generic credential manager can receive the new key on standard input. The retrieval command prints the key on standard output when the MCP server starts:

npx @turtletech/ookcite-mcp setup --connect \
  --store-command "credential-cli store ookcite" \
  --retrieve-command "credential-cli read ookcite"

The installed MCP configuration stores OOKCITE_API_KEY_COMMAND with the retrieval command, not the key. Retrieval receives closed standard input, has a bounded timeout, and cannot copy the credential into diagnostics.

An owner-only file is also available as an explicit choice:

npx @turtletech/ookcite-mcp setup --connect \
  --credential-file "$HOME/.config/ookcite/api-key"

This writes only an OOKCITE_API_KEY_FILE reference to MCP configuration. The file is created with owner-only permissions and is never overwritten.

Credential source precedence is OOKCITE_API_KEY, OOKCITE_API_KEY_COMMAND, OOKCITE_API_KEY_FILE, then the platform credential reference. Existing deployments can continue using setup --key or a manually configured OOKCITE_API_KEY.

Common config file locations#

Client	Config file
Claude Desktop (Linux)	`~/.config/Claude/claude_desktop_config.json`
Claude Desktop (macOS)	`~/Library/Application Support/Claude/claude_desktop_config.json`
Claude Code	`.mcp.json` (project) or `~/.claude/settings.json` (global)
Cursor	Settings > MCP Servers
Windsurf	Settings > MCP
Codex	`~/.codex/config.toml`
OpenCode	`~/.opencode/mcp.json`

For Codex, the equivalent global registration also works from the CLI:

codex mcp add ookcite --env OOKCITE_API_KEY=your_key_here -- npx -y @turtletech/ookcite-mcp

Then restart Codex so the new stdio server starts with the updated environment.

Verify It Works#

Ask your LLM:

"Validate this DOI: 10.1038/187493a0"

You should get back: “Stimulated Optical Radiation in Ruby” by Maiman (1960).

Available Tools#

`validate_doi` – Anti-hallucination#

Check whether OokCite can resolve a DOI and return its metadata. The API checks the local citation corpus before bounded provider fallback. Use this before citing a paper to confirm that the identifier resolves to the expected work.

Input:  { "doi": "10.1038/187493a0" }
Output: Title, authors, year, journal, DOI -- or "not found"

`lookup_isbn` – Book lookup#

Look up a book by ISBN. OokCite checks the local corpus before OpenLibrary fallback.

Input:  { "isbn": "978-0-521-85629-7" }
Output: Title, authors, publisher, year

`reverse_lookup` – Find a paper from messy text#

Paste a citation in any format and OokCite searches its local citation corpus, with bounded provider fallback when local evidence is insufficient.

Input:  { "text": "Maiman 1960 Stimulated Optical Radiation Ruby Nature" }
Output: Ranked candidates with confidence scores

`format_citation` – Format in any CSL style#

Format a citation by DOI in a specific style (APA, IEEE, Chicago, Nature, etc.).

Input:  { "doi": "10.1038/187493a0", "style": "ieee" }
Output: In-text marker "[1]" and bibliography entry

Supported styles: apa, ieee, chicago-author-date, chicago-notes, mla, nature, vancouver, american-chemical-society, and 2900+ more.

`verify_references` – Batch DOI check#

Verify a list of DOIs at once. Returns VALID or INVALID for each.

Input:  { "dois": ["10.1038/187493a0", "10.9999/fake"] }
Output: [ "VALID: Stimulated Optical...", "INVALID: 10.9999/fake" ]

`batch_format` – Format multiple citations#

Resolve and format multiple messy citations in one call.

Input:  { "citations": ["Maiman 1960 Ruby laser Nature", "Einstein 1905 photoelectric"], "style": "apa" }
Output: Formatted numbered reference list

`search_styles` – Find CSL style IDs#

Search for available CSL citation styles by name.

Input:  { "query": "american chemical society" }
Output: Matching style IDs and titles (top 15)

`group_cite` – Grouped in-text citations#

Generate a grouped in-text citation marker (e.g. [1-3]) for multiple DOIs.

Input:  { "dois": ["10.1038/187493a0", "10.1103/PhysRev.47.777"], "style": "ieee" }
Output: Grouped citation string

`health_check` – API status#

Check if the OokCite API is reachable. Use when lookups fail to diagnose connectivity issues.

Input:  {}
Output: Status, version, cache stats

Collection Management (requires sign-in)#

Citation collections are a signed-in feature of OokCite. These tools require an OOKCITE_API_KEY from a paid or free account.

list_collections – List all saved citation collections
add_to_collection – Add a citation by DOI or free-text search (creates collection if needed)
batch_add_to_collection – Add multiple citations at once
import_bibliography – Import BibTeX (.bib) or RIS files into a collection
export_collection – Export a collection as BibTeX
search_collection – Search within a collection by author, title, or journal
check_duplicates – Check if a citation already exists in a collection
delete_collection – Delete a collection (irreversible)
update_collection – Update name, description, or default citation style
remove_from_collection – Remove a specific entry by ID
update_tags – Set tags on a collection
reorder_collection – Reorder entries in a collection

Recommended bibliography workflow#

For longer writing projects, the durable pattern is:

Keep references.bib (or library.bib) in the manuscript repository
Import that file into an OokCite collection with import_bibliography
Use search_collection, check_duplicates, and export_collection during revision
Treat the collection as an audit/export companion, not the only copy of the bibliography

Plans & Pricing#

Tier	Price	Lookups/day	API calls/month	Collections	Entries/collection
Anonymous	Free	20	–	0	–
Free	Free	60	–	4	200
Academic	EUR 4/mo	20,000	10,000	10	1,000
Business	EUR 10/mo	20,000	40,000	20	4,000

Lookups for papers already in your collections are free and unlimited. Only new lookups (papers not yet in a collection) count against your daily quota. Papers stay free to re-lookup as long as they remain in a collection.

Batch formatting and verification use the normal lookup quota. batch_add_to_collection and import_bibliography are available to signed-in Free accounts. merge_collections and batch_move_entries require an Academic or Business plan.

Academic pricing is for students, researchers, and educators at accredited institutions. Business pricing is for everyone else.

Use Cases#

Prevent citation hallucination#

LLMs frequently invent plausible-looking but nonexistent papers. Add this to your system prompt:

"Before including any citation, use the validate\ :sub:`doi`\ tool to confirm the paper
exists. If validation fails, do not include the reference."

For revision workflows, add:

"Keep the project bibliography in a local .bib file under version control.
Use OokCite collections for verification, deduplication, and export."

Format a bibliography for submission#

"Format these 20 DOIs in Nature style using batch\ :sub:`format`\."

Literature review from a PDF#

"Here is a reference list from a PDF. Use reverse\ :sub:`lookup`\ on each entry to find
the DOIs, then format them all in APA style."

No API Key Required#

The MCP server connects to the public OokCite API at ookcite-api.turtletech.us. No API key is needed for basic usage (20 lookups/day). Sign in for 60/day, or upgrade to Academic (EUR 4/mo) or Business (EUR 10/mo) for 20,000/day, included monthly API calls, and larger collections. Sign up at my.turtletech.us.

Set Up the OokCite MCP Server#