Ookcite MCP Server

OokCite MCP Server

Give MCP-capable tools the ability to validate DOIs, format citations, manage bibliography collections, and catch fabricated references. Returns citation metadata only -- not PDFs or full-text articles. Desktop clients can run it over standard input and output. Remote clients use https://ookcite-api.turtletech.us/mcp.

Quick Start

One command to install and configure:

npx @turtletech/ookcite-mcp setup

This auto-detects supported MCP clients and writes the configuration for you. Connect an OokCite account for higher rate limits and collection tools without putting an API key in shell arguments or MCP configuration:

npx @turtletech/ookcite-mcp setup --connect

The command opens the TurtleTech dashboard, creates or activates the Free plan, stores the issued key in the platform credential store, and writes only a credential reference to detected clients. Use setup --connect --device on a headless machine.

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): format_citation and a small plaintext import_bibliography (omit collection, up to 8 items). Sign up for more.

Paste a list to BibTeX

import_bibliography accepts a numbered or blank-line citation list, not only .bib / .ris. Omit collection for a small paste: the tool resolves the items and returns .bib text. With a key, pass collection to save the resolved entries. export_collection can then emit .bib (format=bib) or CSL bibliography text (format=csl or a style id such as ieee). npx @turtletech/ookcite-mcp setup remains the installer. The server never fetches PDFs.

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.

Install (Alternative Methods)

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 (x86_64, aarch64), macOS (x86_64, aarch64), and Windows.

Configure

If you used setup, you're done. Otherwise, add to your MCP client config:

{
  "mcpServers": {
    "ookcite": {
      "command": "npx",
      "args": ["-y", "@turtletech/ookcite-mcp"]
    }
  }
}

With an API key:

{
  "mcpServers": {
    "ookcite": {
      "command": "npx",
      "args": ["-y", "@turtletech/ookcite-mcp"],
      "env": {
        "OOKCITE_API_KEY": "your_key_here"
      }
    }
  }
}

If you installed globally (npm install -g or cargo install), you can use "command": "ookcite-mcp" directly instead of npx.

Keeping the key out of the config file

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

A generic credential manager can be used instead. The store command receives the new key on standard input; it must not expect the key in a command-line argument. 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"

For an explicit owner-only file instead of a credential manager:

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

The file is created with owner-only permissions and is never overwritten. The platform, helper-command, and file forms put references such as these in client configuration:

{
  "mcpServers": {
    "ookcite": {
      "command": "npx",
      "args": ["-y", "@turtletech/ookcite-mcp"],
      "env": {
        "OOKCITE_API_KEY_COMMAND": "credential-cli read ookcite"
      }
    }
  }
}

At startup, source precedence remains OOKCITE_API_KEY, OOKCITE_API_KEY_COMMAND, OOKCITE_API_KEY_FILE, then the platform credential reference. With none of them the server starts anonymous. setup --key remains available for existing deployments that intentionally keep the key in client configuration.

Credential retrieval obeys two constraints:

• Retrieval receives closed standard input, so it cannot consume MCP JSON-RPC.
• Retrieval is bounded by OOKCITE_API_KEY_TIMEOUT, which defaults to 10 seconds, and its output is never copied into diagnostics.

Consult your client's MCP documentation for its configuration-file location. Use the mcpServers.ookcite JSON above when automatic setup is unavailable, then restart the client or reload its MCP servers.

Optional env (stdio MCP, all clients):

Marketplace plugin

OokCite installs two ways.

From this repository, add marketplace TurtleTech-ehf/ookcite-mcp and install ookcite@ookcite. That registers the ookcite marketplace and enables the plugin in plugins/ookcite. The plugin connects to https://ookcite-api.turtletech.us/mcp and adds three skills: format a pasted bibliography (/ookcite:format-bibliography), verify references before submission (/ookcite:verify-references), and build and export a collection (/ookcite:build-collection). Sign in when asked. Formatting one citation and checking a short DOI list also work before sign-in, within the anonymous daily cap. Saving a collection requires the signed-in account.

The web, desktop, and cowork apps use the same address as a directory connector. Choose sign-in. Submit the connector by that URL, and submit the plugins/ookcite folder as the plugin bundle. Installing from the marketplace does not submit either listing.

A remote connector does not have to support dynamic client registration. The plugin sends the pre-registered public client id ookcite-remote, so the code client does not call a registration endpoint. Discovery for that client publishes S256 PKCE and no registration_endpoint. The protected resource lists that client's issuer first, and its resource field is https://ookcite-api.turtletech.us/mcp. The client accepts the directory callback exactly, and loopback redirects on localhost and 127.0.0.1 at any port. Access tokens must satisfy exp - iat <= 3600 or the resource server rejects them.

Remote MCP

Use OokCite from a chat product without installing anything. Add this address, choose sign-in, and approve the login when asked:

https://ookcite-api.turtletech.us/mcp

The chat then sends a short-lived access token:

Authorization: Bearer <access token>

Lookups count against that signed-in account. A pasted API key is rejected. The transport is stateless Streamable HTTP: one POST, JSON in and JSON out. Select Streamable HTTP and sign-in (OAuth). Do not select the legacy SSE transport, an API key, or "No authentication".

eduGenAI Chat, after ookcite-api.turtletech.us is whitelisted:

ookcite-mcp serve runs your own copy. Desktop clients that spawn a subprocess still use standard input and output.

MCP usage tips

• Prefer batch tools (verify_references, batch_format, batch_add_to_collection, import_bibliography) over many single-citation calls.
• Collection mutations require the signed-in account, or OOKCITE_API_KEY on a copy you run yourself. Destructive tools (delete_collection, remove_from_collection, unshare_collection) are annotated for clients that honor MCP tool hints.
• The server writes diagnostics to stderr only on the MCP path; stdout is reserved for JSON-RPC.

Tools

Lookup & Validation

Formatting

Account

ORCID

Collections (requires sign-in)

Collections are a signed-in feature. The hosted server uses the account from sign-in. A copy you run yourself uses OOKCITE_API_KEY. A small plaintext import_bibliography with no collection is the exception: it returns .bib under the anonymous cap.

Typical workflow:

1. Paste a numbered citation list into import_bibliography (omit collection for a small list) and keep the returned .bib
2. Or keep references.bib / library.bib under version control and import that file into a collection
3. Use search_collection, check_duplicates, and export_collection (bib or csl) while revising
4. Treat the collection as an audit/export companion, not the only copy of your bibliography

Removing a single entry: call search_collection (or check_duplicates) to see each hit as entry_id: … (and optionally aliases: doi:… when the stored id is opaque). Pass that entry_id to remove_from_collection, or pass the paper's bare DOI / doi:10.x/y — the server resolves aliases locally before the API call.

Sharing & Collection Operations

Sharing is available to signed-in accounts with collections. Free accounts can import and batch-add within their daily quota. Merge and batch-move require an Academic or Business plan.

Utilities

These three require an Academic or Business plan.

Plans & Pricing

Re-lookups can be served without quota use when collection metadata is already available to the API. A retrieval that has to resolve the paper again can count against the current plan's quota. Paid Academic checkout is intended for students, researchers, and educators at accredited institutions; a verified ORCID can also qualify a signed-in account for Academic limits.

Anti-Hallucination

Add this to your system prompt:

Before citing any paper, use validate_doi to confirm the reference exists. If validation fails, do not include the citation.

For revision workflows, add:

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

How It Works

The MCP server connects to the public OokCite API to look up and format citations. It's a thin MCP wrapper around the OokCite REST API with no local database, and no heavy dependencies.

Sign up for a free account (60 lookups/day), or upgrade to Academic (EUR 4/mo) or Business (EUR 10/mo) for higher monthly API limits, larger collections, paid utilities, merge, and batch-move.

Source layout

The crate is a thin MCP (stdio) wrapper around the public OokCite REST API. There is no local citation database; all state lives on the API.

Collections / entry ids: search_collection and check_duplicates emit entry_id: … lines. remove_from_collection accepts that id, a bare DOI, or doi:10.x/y (resolved locally in collection_entries before the DELETE call).

Release: tag v* runs .github/workflows/release.yml (multi-arch GitHub Release assets, crates.io, npm). Version bumps use cocogitto (cog.toml + scripts/set-version.sh).

Why server.rs is large: rmcp's #[tool_router] / #[tool] macros keep handlers on one impl Server. Further file splits without macro workarounds add little user value; peel tests or add small helpers (resolve_many, shared Me type) before fighting the macro.

Contributing / local checks

cargo test --bin ookcite-mcp          # unit tests (no contract key needed)
cargo build --release
./target/release/ookcite-mcp --version

# Contract tests (optional locally; required in CI with secret):
export OOKCITE_CONTRACT_KEY="value-from-your-credential-manager"
cargo test --test api_contract

Live MCP smoke (optional; needs OOKCITE_API_KEY): add/search/remove with a bare DOI on a throwaway collection, then delete_collection.

Documentation

• Full MCP setup guide
• OokCite app
• TurtleTech

License

MIT. see LICENSE.