mcp-openidea-search

An MCP server that exposes Open Idea's federated search — across open-knowledge providers (OpenAlex, arXiv, Zenodo, Software Heritage, GitHub, GitLab, HuggingFace, PapersWithCode, YouTube, CKAN, Figshare, Kaggle) — to MCP-compatible clients (Claude Desktop, Claude Code, the MCP Inspector, Cursor, etc.).

This package is a thin client over the Open Idea v1 HTTP API. All the federation, deduplication, normalization, and caching happen on Open Idea's side. This repo is fully standalone — no dependency on the Open Idea codebase.

Documentation

Doc	Contents
docs/setup.md	Install, configure, and run the server.
docs/architecture.md	Components, flows, and a Mermaid diagram.
docs/api-reference.md	Every tool, resource, and data model.
docs/claude-desktop.md	Claude Desktop configuration (macOS/Windows/Linux).
docs/claude-code.md	Claude Code registration & verification.
docs/mcp-inspector.md	Testing with the MCP Inspector.
docs/troubleshooting.md	401s, newline keys, startup failures, and more.
docs/development.md	Repo layout, env setup, tests, workflow.

🚀 Getting Started

This tool connects Claude directly to Open Idea's academic and data search engines. It runs entirely on your local machine using your personal API key. Follow these 4 simple steps to get set up.

Prerequisites

Make sure you have Python 3.10 or higher installed on your computer. You can check this by running python --version in your terminal.

---

Step 1: Get Your Free Open Idea API Key

Because this tool queries live databases on your behalf, you need a personal access key.

1. Go to openidea.world and sign up or log in.
2. Navigate to the Developer Dashboard at openidea.world/developer/api-keys.
3. Click Create New Key.
4. ⚠️ Copy the key immediately (it starts with oi_live_...). It will only be shown to you once.

---

Step 2: Install the Search Tool

Open your terminal (Terminal on Mac/Linux, or PowerShell/Command Prompt on Windows) and run the following command to safely install the tool:

pipx install mcp-openidea-search

(If you do not have pipx configured, you can use pip install mcp-openidea-search instead).

---

Step 3: Connect It to Your Claude Client

Choose the instructions below depending on whether you use Claude Code (in your terminal) or the Claude Desktop App.

Option A: For Claude Code (Terminal)

1. Close any active Claude sessions by typing exit.
2. Run this exact command in your terminal (make sure to replace YOUR_KEY_HERE with the actual key you copied in Step 1):

claude mcp add openidea \
  -e OPENIDEA_API_URL=https://www.openidea.world \
  -e OPENIDEA_API_KEY=YOUR_KEY_HERE \
  -- mcp-openidea-search stdio

Option B: For Claude Desktop (App)

1. Open your Claude Desktop configuration file. Paste the path below into your file explorer or terminal to open it:
   • Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
2. Open the file in a text editor (like Notepad or VS Code) and add the following configuration block inside the "mcpServers" section (replace YOUR_KEY_HERE with your actual key):

{
  "mcpServers": {
    "openidea": {
      "command": "mcp-openidea-search",
      "args": ["stdio"],
      "env": {
        "OPENIDEA_API_URL": "https://www.openidea.world",
        "OPENIDEA_API_KEY": "YOUR_KEY_HERE"
      }
    }
  }
}

3. Completely restart your Claude Desktop application.

---

Step 4: Try It Out!

You are all set! You do not need to run this tool manually; Claude will wake it up when needed. Open a chat with Claude and ask a natural question:

💬 "Use the openidea MCP to find recent papers on transformer architectures."

Claude will automatically look up the records, pull data from arXiv, GitHub, or HuggingFace, and summarize the answers for you!

Install

Requires Python 3.10+.

# from PyPI (once published)
pipx install mcp-openidea-search

# or directly from source
pip install -e .

Configure

The server reads two environment variables:

Variable	Required	Description
OPENIDEA_API_URL	yes	Base URL of the Open Idea API (https://www.openidea.world in production). A trailing slash is stripped automatically.
OPENIDEA_API_KEY	yes	Personal Bearer key. Mint one at https://openidea.world/developer/api-keys while signed in. The plaintext is shown only once at creation.

Both values are whitespace/newline-trimmed before use.

Run

stdio (Claude Desktop / Claude Code)

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent on your OS (see docs/claude-desktop.md):

{
  "mcpServers": {
    "openidea": {
      "command": "mcp-openidea-search",
      "args": ["stdio"],
      "env": {
        "OPENIDEA_API_URL": "https://www.openidea.world",
        "OPENIDEA_API_KEY": "oi_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

For Claude Code, register it with the CLI (see docs/claude-code.md):

claude mcp add openidea \
  -e OPENIDEA_API_URL=https://www.openidea.world \
  -e OPENIDEA_API_KEY=oi_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx \
  -- mcp-openidea-search stdio

Restart your client and ask: "use the openidea MCP to search for transformer architectures".

HTTP/SSE (remote)

OPENIDEA_API_URL=https://www.openidea.world \
OPENIDEA_API_KEY=oi_live_xxx \
mcp-openidea-search http --host 0.0.0.0 --port 8000

Verify with the MCP Inspector:

npx @modelcontextprotocol/inspector http://localhost:8000/sse

Tools and resources

Tools

Name	Description
search_papers	Search for papers (OpenAlex, arXiv, PapersWithCode).
search_code	Search for code repos (GitHub, GitLab, Software Heritage).
search_datasets	Search for datasets (Zenodo, CKAN, Figshare, Kaggle).
search_models	Search for ML models (HuggingFace).
search_hardware	Search for open hardware.
search_videos	Search for educational videos (YouTube).
search_all	Search across all providers. Accepts an optional types: string[] filter.

Each tool takes query: string and optional limit: integer (default 20, range 1–100). Returns a JSON payload { results: Resource[], total: number, … }. Full schemas and response shapes are in docs/api-reference.md.

Resources

Single items addressable by URI (openidea://<provider>:<id>):

openidea://openalex:W2741809807
openidea://github:vercel/next.js

Listing resources returns an empty array — they're addressable but not enumerable. Use the search tools to discover ids, then read_resource to fetch the canonical record.

Develop

python -m venv .venv
source .venv/bin/activate     # Windows: .venv\Scripts\Activate.ps1
pip install -e ".[dev]"
pytest -q

See docs/development.md for the full contributor guide.

Troubleshooting

Symptom	Likely cause
401 unauthorized errors	Key is missing, malformed, has a stray newline, or has been revoked. Mint a new one.
429 rate_limited	Throughput limit on this key (server retries once). Wait or use a second key.
Empty results	Upstream provider down, or type filter excludes all results. Try search_all.
connection refused	OPENIDEA_API_URL doesn't point to a running Open Idea instance.

Full guide: docs/troubleshooting.md.

License

MIT.