Skip to content
BranchesTags

Repository files navigation

🧠 ResearchMind MCP Server

Give your AI coding assistant a research brain.

Python License MCP GitHub

What This Does

ResearchMind connects to Cursor, VS Code (Cline), Claude Desktop, Windsurf, or any MCP-compatible AI assistant and gives it a persistent research memory. Your AI can search arXiv, download and ingest PDFs, save notes organized by project, and answer questions grounded in everything you've read — across sessions, across projects.

No cloud. No accounts.

🚀 Quick Start

Step 1 — Clone & Install

git clone https://github.com/suraj5424/Researchmind_MCP_Server.git
cd Researchmind_MCP_Server
python -m venv .venv

Windows: .venv\Scripts\activate
Mac/Linux: source .venv/bin/activate

pip install -r requirements.txt

Install time: Fast — no torch or sentence-transformers needed. The embedding model (~90 MB) auto-downloads from Google Drive on first server run.

Model auto-download: The first time you run the server, it automatically downloads all-MiniLM-L6-v2.onnx from Google Drive into models/embeddings/. No manual download needed. To use a custom model location, set EMBEDDING_MODEL_PATH or EMBEDDING_MODEL_URL environment variables.

Step 2 — Connect to Your AI

Universal Base Config (works with Cursor, Claude Desktop, Windsurf, Continue.dev, etc.):

{
  "mcpServers": {
    "researchmind": {
      "type": "stdio",
      "command": "/path/to/your/venv/python",
      "args": ["/path/to/Researchmind_MCP_Server/server.py"]
    }
  }
}

Cline on Windows — Workspace Awareness: Configure this based on the local path where you cloned the repository.

{
  "mcpServers": {
    "researchmind": {
      "type": "stdio",
      "command": "D:\\Projects\\MCP_server creation\\.mcp_server_venv\\Scripts\\python.exe",
      "args": ["D:\\Projects\\MCP_server creation\\server.py"],
      "env": {
        "CLINE_WORKSPACE_FOLDER": "${workspaceFolder}"
      }
    }
  }
}

💡 Workspace Awareness: Set the workspace environment variable to the local path of your cloned repository. For Cline, use CLINE_WORKSPACE_FOLDER. Other clients (such as Kilo Code, Cursor, Claude Code, and Codex) may use a different workspace variable (for example, KILO_WORKSPACE_FOLDER, CLAUDE_PROJECT_DIR, or CODEX_WORKSPACE_DIR). Check your client's documentation for the correct variable. If your client does not support a workspace variable, remove the env block. The server will then use its default workspace folder.

Step 3 — Done ✅

Now try saying to your AI:

"Search arXiv for the latest on retrieval-augmented generation and save the top papers in a workspace called 'rag-research'."

✨ Key Features

Say this to your AI... And it'll...
"Find papers on vision transformers" Search arXiv and return structured results
"Save this insight" Create a note in your current workspace
"Download paper 2306.15595" Fetch the PDF, extract text, index it for search
"What do my papers say about sparse attention?" Search your ingested PDFs, return cited passages
"Find related notes across all projects" Semantic search across everything you've saved
"Build a research report on fine-tuning" Assemble your notes into a structured markdown report
"Check system health" Verify server, vector store, and metadata DB are healthy

💡 How It Helps You

"I read papers but my AI doesn't know what I've read."

ResearchMind gives your AI a persistent research memory. Save notes and your AI can search across everything — even across different projects and sessions. No more repeating yourself.

"I waste time re-finding papers and notes."

Search arXiv directly from your AI and download PDFs with download_paper. Papers are automatically indexed for search (set auto_ingest=false to skip). Once indexed, query your whole library semantically — across projects — instead of digging through folders. (Note: strip version suffixes like v4 from arXiv IDs before downloading; download_paper rejects versioned IDs like 2501.19389v4.)

"I need answers grounded in actual papers, not guesses."

After downloading a paper (with auto_ingest=true, the default), ask "What do my papers say about sparse attention?" — ResearchMind retrieves exact passages from ingested PDFs with citations (source, workspace, chunk, score). Use ask to query your knowledge base.

"I work across multiple projects and lose context."

Workspaces keep research organized by project. Semantic search works across all of them. Ask "Find related notes across all projects" (leave workspace empty = search all) and get results from everything you've saved.

"I want to build a literature review without manual grunt work."

The build_report tool surveys your notes (including paper summaries saved as notes) on a topic and assembles a structured markdown report. For PDF-grounded answers, use ask.

"I don't want my research data leaving my machine."

Everything runs locally — embeddings (ONNX Runtime, CPU), vector storage (ChromaDB on disk), metadata (SQLite). No accounts, no cloud sync. The only network calls are arXiv search and the one-time embedding model download. Optional local-only telemetry exists but is off unless you set RESEARCHMIND_TELEMETRY=1.

"I'm not sure it's worth the setup time."

Setup is pip install -r requirements.txt plus a one-time model download. The runtime is torch-free — embeddings run on ONNX Runtime (CPU), so no heavy torch/sentence-transformers dependency. On a fresh machine, expect a few minutes for the lightweight install (~0.5 GB). After that, every research session with your AI becomes more productive. The time you save finding papers, recalling notes, and re-explaining context adds up fast.

🏗️ Architecture

┌─ Your AI Assistant ──────────────────────────┐
│  Cursor · Cline · Claude Desktop · Windsurf  │
│         │  talks MCP protocol over stdio     │
└─────────┼────────────────────────────────────┘
          │
┌─────────▼────────────────────────────────────┐
│           ResearchMind Server                 │
│                                               │
│  ┌──────────┐  ┌──────────┐  ┌───────────┐  │
│  │  Notes   │  │  arXiv   │  │  Papers   │  │
│  │  Tools   │  │  Tools   │  │  Tools    │  │
│  └────┬─────┘  └────┬─────┘  └─────┬─────┘  │
│       │              │              │         │
│       └──────────────┴──────────────┘         │
│                      │                        │
│  ┌───────────────────▼────────────────────┐  │
│  │         Service Layer                   │  │
│  │  ┌────────────┐  ┌──────────────────┐  │  │
│  │  │ Embeddings │  │  Vector Store    │  │  │
│  │  │(ONNX Run  │  │  (ChromaDB)      │  │  │
│  │  │ time, CPU) │  │                  │  │  │
│  │  └────────────┘  └──────────────────┘  │  │
│  │  ┌────────────┐  ┌──────────────────┐  │  │
│  │  │ Metadata   │  │  PDF Extractor   │  │  │
│  │  │ (SQLite)   │  │  (PyMuPDF)       │  │  │
│  │  └────────────┘  └──────────────────┘  │  │
│  └────────────────────────────────────────┘  │
└──────────────────────────────────────────────┘

The flow:

  1. You ask your AI a question ("What do my papers say about attention mechanisms?")
  2. Your AI calls the ask tool on ResearchMind
  3. ResearchMind embeds your question with the same local ONNX model used for ingestion
  4. That vector hits ChromaDB with hybrid BM25 + vector search
  5. Top chunks return with citations (source, workspace, chunk ID, score)
  6. Your AI synthesizes a grounded answer

No data leaves your machine. No API keys. No cloud accounts.

🛠️ The Tools

Category Tools
Workspace (4) create_workspace · list_workspaces · delete_workspace · set_workspace_root
Notes (7) create_note · list_notes · read_note · delete_note · summarize_note · build_report · list_templates
Research (1) search_arxiv
Papers (4) download_paper · list_papers · open_paper · delete_paper
Search & Q&A (2) search · ask
System (1 public + 2 admin) system_status · rebuild_registry · refresh_embeddings

🔧 Configuration

The project uses a config.json file for easy configuration:

{
  "workspace_root": null,
  "embedding": {
    "model_path": "./models/embeddings/all-MiniLM-L6-v2.onnx",
    "model_url": "https://drive.google.com/uc?export=download&id=1OvoK6Lg6rPktKwg73ggsB-EJk1ZzF6HJ",
    "dimension": 384
  },
  "vector_store": {
    "chroma_db_path": "./data/chroma_db"
  },
  "chunking": {
    "mode": "semantic",
    "max_chunk_words": 500,
    "min_chunk_words": 100
  },
  "hybrid_search": {
    "enabled": true,
    "bm25_weight": 0.5,
    "vector_weight": 0.5
  }
}

Key settings:

  • workspace_root: Override where workspaces are created (default: auto-detect)
  • embedding.model_url: Custom model download URL (useful if Google Drive is blocked)
  • hybrid_search: Toggle hybrid search and adjust BM25 vs vector weights

⚙️ The Details I Care About

I built this like I'd build any production tool — sweating the small stuff that matters when you use it every day.

Being a Good arXiv Citizen

arXiv is a free service run by Cornell. ResearchMind treats it with respect:

  • 2-second delay between every API call
  • Automatic retry with backoff if a request hiccups
  • 15-second timeout — if arXiv is slow, you get an empty result, not a hang
  • Graceful degradation — if arXiv is down, the tool returns {"papers": [], "total_count": 0} cleanly

Resource Management That Doesn't Leak

  • PDF downloads: 30-second timeout, size validation, MIME-type checking
  • Path safety: No writes outside designated directories, ever
  • Registry fallback: If SQLite is locked or corrupted, automatically falls back to filesystem scanning

Cleanup That Actually Cleans Up

Delete a paper and it's gone:

  • PDF file removed
  • SQLite metadata row removed
  • All ChromaDB vectors for that paper removed
  • Deletion verified and reported

Local-First, By Default

Embeddings (ONNX Runtime, CPU), vector storage (ChromaDB on disk), metadata (SQLite) — all local. No accounts, no sync, no telemetry unless you explicitly set RESEARCHMIND_TELEMETRY=1. The only network calls are arXiv search and the one-time model download.

Startup That Doesn't Make You Wait

  • Pre-warmed embeddings — model loads at startup, first query is fast
  • Background DB init — ChromaDB and SQLite warm up while the server is already serving
  • Thread-safe — ONNX Runtime has no C-extension threading constraints, so pre-warming is synchronous and reliable

Search That Finds What You Mean

Hybrid BM25 + vector similarity by default:

  • BM25 catches exact terminology ("LoRA", "RAG", "flash attention")
  • Vector catches conceptual matches ("efficient fine-tuning" → "LoRA")
  • 50/50 fusion out of the box, tunable via config
  • MMR diversification so you don't get five chunks from the same paper

⚖️ Design Decisions & Trade-offs

A few deliberate choices:

Embedding Model: 384-D all-MiniLM-L6-v2

Smaller than 768/1024-d models, intentionally:

Factor Choice Rationale
Compute CPU-first, no GPU/torch ONNX Runtime on modest hardware
Footprint ~0.5 GB Small indexes, fast ops
Quality Strong for technical retrieval Paper abstracts, code-adjacent notes
Flexibility Swappable embedding.model_path / model_url in config

No Predefined Skill Categories (Craftsman Approach)

  • Your mental model > generic taxonomy — no forced buckets
  • Templates over categories — list_templates / create_note with template_id for your own types (lit review, experiment log, ADR, etc.)
  • Search replaces classification — hybrid search means you just ask

Hybrid Search (BM25 + Vector)

  • BM25 → exact terms: "LoRA", "flash attention", "2306.15595"
  • Vector → concepts: "efficient fine-tuning" → LoRA papers
  • 50/50 fusion default, tunable in config.json

MMR Re-ranking

  • First result by pure relevance
  • Subsequent balance relevance vs. dissimilarity to selected
  • Lambda=0.7 default (tunable) — broader coverage per query

Overall Balance

Dimension Choice Rationale
Retrieval quality Hybrid BM25 + Vector + MMR Best practical recall for technical content
Latency 384-d ONNX on CPU, pre-warmed Sub-100ms on typical laptop
Compute efficiency No torch, no GPU, ~0.5 GB RAM Runs anywhere Python runs
Ease of use Auto model download, single config, stdio MCP Zero-config for 90%; extensible for rest

🤔 Why I Built This

I read a lot of papers. I code with AI assistants a lot. And for the longest time, those two workflows didn't talk to each other.

Every time I started a new chat, I had to re-explain the papers I'd read, re-paste the relevant sections, re-establish context. My AI had no memory. It felt like working with a brilliant colleague who gets amnesia every morning.

So I built the bridge I needed: an MCP server that sits locally, indexes everything I throw at it, and makes it all available to my AI through a clean tool interface. No dashboards, no login screens, no telemetry phoning home. Just a Python process that does one thing well.

📄 License

MIT — free to use.

Built by suraj5424

About

ResearchMind MCP Server gives AI assistants a local research brain with RAG, semantic search, arXiv integration, and persistent memory. Built with Python, ONNX Runtime, ChromaDB, and SQLite.

Topics

chromadb-vector-searchhybrid-searchmcp-serveronnxruntimeragreranking-mechanismsqlite3systemdesign

Resources

Readme
MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Contributors

Languages