OokCite MCP Server

Give any LLM the ability to validate DOIs, format citations, manage bibliography collections, and catch hallucinated references. Returns citation metadata only -- not PDFs or full-text articles. Works with any MCP client: Grok Build, Claude, Codex, Cursor, Windsurf, OpenCode, Qwen agents, and more.

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.

Common config file locations:

Grok Build

Recommended: install from the xAI plugin marketplace once published (/marketplace in Grok Build, search for ookcite). The marketplace entry clones this repo at a pinned commit and loads the bundled .mcp.json + plugin.json.

From this repo (local / PR testing):

grok plugin install /path/to/ookcite-mcp
# or from git once plugin files are on the branch you pin:
# grok plugin install https://github.com/TurtleTech-ehf/ookcite-mcp.git

Set OOKCITE_API_KEY in your shell or Grok env for collection tools (optional for basic lookup/format tools). Trust the plugin when prompted so its MCP server is allowed to start.

Manual MCP config (same payload as other clients; Grok also loads project .mcp.json at the repo root):

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

This repository ships that config as .mcp.json plus plugin.json for Grok plugin discovery. After changing MCP config, restart Grok or reload MCP servers.

Optional env (stdio MCP, all clients):

Claude Desktop / Claude Code

ookcite-mcp setup uses add-mcp for most Claude installs. Manual fallback uses the same mcpServers.ookcite JSON as above:

Restart the app or reload MCP servers after edits.

Codex

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. You can also declare [mcp_servers.ookcite] in ~/.codex/config.toml.

MCP / agent 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

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 & Bulk Operations (requires academic/business plan)

Plans & Pricing

Papers in your collections are free and unlimited to re-lookup. Only new lookups count against your daily quota. Papers stay free as long as they remain in a collection.

Batch operations require an academic or business plan. Academic pricing is for students, researchers, and educators at accredited institutions.

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 (30 lookups/day), or upgrade to academic ($4/mo) or business ($12/mo) for batch operations and larger collections.

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.

Quick Start

One command to install and configure:

npx @turtletech/ookcite-mcp setup

This auto-detects supported MCP clients (Claude Desktop, Claude Code, Cursor, Codex) and writes the config for you. Grok Build is not covered by setup — install via the plugin marketplace or the Grok config below. 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 (10 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.