🎓 Q1 Crafter MCP

Academic Research MCP Server for Claude Desktop
Automates the full research cycle — from source discovery across 18 databases
to Q1-quality, APA 7-formatted .docx output.

Features • Quick Start • Claude Desktop • Tools • Sources • Contributing

✨ Features

🚀 Quick Start

Installation

pip install q1-crafter-mcp

Configuration

# Copy the example env file
cp .env.example .env

# Add your API keys (optional — free sources work without any keys!)
# Edit .env and fill in the keys you have

Run

q1-crafter-mcp

🖥️ Claude Desktop Setup

Add to your Claude Desktop configuration file:

{
  "mcpServers": {
    "q1-crafter": {
      "command": "q1-crafter-mcp",
      "env": {
        "SCOPUS_API_KEY": "your-scopus-key",
        "IEEE_API_KEY": "your-ieee-key",
        "SPRINGER_API_KEY": "your-springer-key",
        "NCBI_API_KEY": "your-pubmed-key",
        "UNPAYWALL_EMAIL": "your-email@example.com"
      }
    }
  }
}

{
  "mcpServers": {
    "q1-crafter": {
      "command": "q1-crafter-mcp",
      "env": {
        "SCOPUS_API_KEY": "your-scopus-key",
        "IEEE_API_KEY": "your-ieee-key",
        "SPRINGER_API_KEY": "your-springer-key"
      }
    }
  }
}

💡 Tip: You don't need all API keys! Free sources (arXiv, CrossRef, OpenAlex, PubMed, etc.) work out of the box. Add paid keys to unlock more databases.

🛠 Available Tools

🔍 Search Tools

📊 Analysis Tools

📈 Visualization Tools

📝 Output Tools

🌐 Supported Sources

🏗 Architecture

q1-crafter-mcp/
├── src/q1_crafter_mcp/
│   ├── server.py            # MCP server + 14 tool registrations
│   ├── config.py            # Settings & API key management
│   ├── models.py            # Pydantic data models
│   └── tools/
│       ├── search/          # 18 API clients + aggregator + dedup
│       ├── analysis/        # Gap analyzer, keywords, summarizer
│       ├── visualization/   # Charts, tables, citation network
│       └── output/          # APA formatter, section writer, DOCX
├── tests/                   # 120 unit tests
├── pyproject.toml
└── .env.example

How It Works

graph LR
    A[Claude Desktop] -->|MCP| B[Q1 Crafter Server]
    B --> C[🔍 Search 18 APIs]
    C --> D[🔄 Deduplicate]
    D --> E[📊 Analyze]
    E --> F[📈 Visualize]
    E --> G[📝 APA 7 Format]
    G --> H[📄 .docx Output]

1. Search — Queries up to 18 databases in parallel, routes by field (medicine → PubMed, CS → Semantic Scholar)
2. Deduplicate — Removes duplicates via exact DOI + fuzzy title matching (92% threshold)
3. Analyze — Identifies themes, gaps, trends, and extracts keywords
4. Visualize — Generates charts, tables, and citation networks
5. Format — Applies APA 7th edition rules for citations and references
6. Output — Assembles everything into a formatted .docx manuscript

📖 Usage Example

Just ask Claude naturally:

🗣 "Search for papers about machine learning in drug discovery from 2020-2024, analyze the results, and generate a literature review section with APA 7 citations."

Claude will automatically:

1. Search across available databases
2. Deduplicate and rank results
3. Analyze themes and identify gaps
4. Generate formatted citations
5. Write a structured section with proper references

🔑 API Key Setup

🧪 Development

# Clone the repo
git clone https://github.com/ZaEyAsa/q1-crafter-mcp.git
cd q1-crafter-mcp

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Lint
ruff check src/

📊 Test Coverage

📄 License

MIT © ZaEyAsa

Built with ❤️ for researchers who deserve better tools.
_{If this helps your research, give it a ⭐ on GitHub!}