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. Works with clients that support MCP servers over standard input and output.

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. Add an API key for higher rate limits and collection tools:

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.

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

npm/scripts/ookcite-mcp-credential-helper fetches the key at launch and execs the server, so the config names a command instead of holding a secret:

{
  "mcpServers": {
    "ookcite": {
      "command": "/path/to/ookcite-mcp-credential-helper",
      "env": {
        "OOKCITE_API_KEY_COMMAND": "pass show services/ookcite-api-key"
      }
    }
  }
}

It also takes OOKCITE_API_KEY_FILE for a plain file, and OOKCITE_API_KEY still wins if it is already set. With none of them the server starts anonymous.

Write your own wrapper instead and two things will bite, both of which present as the server hanging rather than as a credential error:

• Anything run before exec inherits stdin, which belongs to the client. A helper that reads stdin consumes the initialize request; the server then waits for a message that is already gone until the client gives up. Redirect every command from /dev/null.
• A secret store can block indefinitely. gpg asks for a passphrase over its own agent socket, which </dev/null does not reach, so a locked key parks the launch on a prompt the client never shows. Bound the lookup well inside the client's connect timeout; OOKCITE_API_KEY_TIMEOUT defaults to 10 seconds.

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):

MCP usage tips

• Prefer batch tools (verify_references, batch_format, batch_add_to_collection, import_bibliography) over many single-citation calls.
• Collection mutations require OOKCITE_API_KEY. 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. Set OOKCITE_API_KEY to use these tools.

Typical workflow:

1. Keep references.bib or library.bib under version control in your project
2. Import that file into an OokCite collection with import_bibliography
3. Use search_collection, check_duplicates, and export_collection 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=$(pass show turtletech/ookcite-contract-key)
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.