๐ 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
| Category | Highlights |
|----------|-----------|
| ๐ **Multi-Source Search** | Query **18 academic APIs** in parallel with smart field-based routing |
| ๐ **Intelligent Dedup** | Two-phase deduplication: exact DOI match โ fuzzy title (92% Levenshtein) |
| ๐น๐ท **Turkish Sources** | Native support for TR Dizin, DergiPark (OAI-PMH), YรK Tez Merkezi |
| ๐ **Literature Analysis** | Gap detection, keyword extraction (TF-IDF), citation validation |
| ๐ **Visualizations** | Publication trends, source distribution, citation network (Mermaid) |
| ๐ **APA 7 Engine** | Full citation formatter โ handles 1/2/3+/20+ author rules, DOI formatting |
| ๐ **DOCX Generator** | One-click manuscript generation with title page, sections, references |
| โก **Zero Config** | Free sources work instantly; paid APIs activate when keys are provided |
---
## ๐ Quick Start
### Installation
```bash
pip install q1-crafter-mcp
```
### Configuration
```bash
# 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
```bash
q1-crafter-mcp
```
---
## ๐ฅ๏ธ Claude Desktop Setup
Add to your Claude Desktop configuration file:
๐ Windows โ %APPDATA%\Claude\claude_desktop_config.json
```json
{
"mcpServers": {
"q1-crafter": {
"command": "python",
"args": ["-m", "q1_crafter_mcp.server"],
"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"
}
}
}
}
```
๐ macOS / Linux โ ~/Library/Application Support/Claude/claude_desktop_config.json
```json
{
"mcpServers": {
"q1-crafter": {
"command": "python3",
"args": ["-m", "q1_crafter_mcp.server"],
"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.
---
## ๐ง Troubleshooting
โ ENOENT error: spawn q1-crafter-mcp ENOENT
This means Claude Desktop can't find the executable. This is common on Windows because `pip install` puts scripts in a user directory that isn't in Claude Desktop's PATH.
**Fix:** Use `python -m` instead of the direct command (already shown in the config above). Make sure you're using:
```json
"command": "python",
"args": ["-m", "q1_crafter_mcp.server"]
```
**Alternative fix:** Use the full path to the executable:
```bash
# Find where it's installed:
pip show q1-crafter-mcp
# Look at the "Location" field, then the Scripts folder next to it
# Example: C:\Users\YourName\AppData\Roaming\Python\Python313\Scripts\q1-crafter-mcp.exe
```
Then use that full path in your config:
```json
"command": "C:\\Users\\YourName\\AppData\\Roaming\\Python\\Python313\\Scripts\\q1-crafter-mcp.exe"
```
โ Server disconnected immediately
Check that the package is installed correctly:
```bash
python -m q1_crafter_mcp.server
```
If you get an import error, reinstall:
```bash
pip install --force-reinstall q1-crafter-mcp
```
โ No search results returned
- Free sources (arXiv, CrossRef, OpenAlex) work without API keys
- If you added API keys, verify they are correct in your Claude Desktop config
- Run `check_api_status` tool in Claude to see which sources are available
---
## ๐ Available Tools
### ๐ Search Tools
| Tool | Description |
|------|-------------|
| `search_academic` | Search up to 18 databases in parallel with smart routing |
| `search_by_doi` | Look up any paper by its DOI |
| `search_citations` | Find all papers that cite a given work |
| `search_references` | Get the reference list of a paper |
### ๐ Analysis Tools
| Tool | Description |
|------|-------------|
| `analyze_literature` | Identify research gaps, themes, trends, and top-cited papers |
| `validate_citations` | Bidirectional check: in-text citations โ reference list |
| `extract_keywords` | TF-IDF keyword extraction with bigram support |
### ๐ Visualization Tools
| Tool | Description |
|------|-------------|
| `generate_comparison_table` | Paper comparison tables (Markdown, CSV, APA format) |
| `generate_trend_chart` | Publication trend charts (base64 PNG, dark theme) |
| `generate_citation_network` | Citation network visualization (Mermaid diagram) |
### ๐ Output Tools
| Tool | Description |
|------|-------------|
| `write_section` | Academic section scaffolding with IMRaD templates |
| `format_references_apa7` | APA 7th edition reference list formatter |
| `build_docx` | Generate formatted `.docx` manuscript |
| `check_api_status` | Check which API sources are available |
---
## ๐ Supported Sources
| ๐ Free (No Key) |
๐ Free (Key Required) |
๐๏ธ Institutional |
๐น๐ท Turkish |
|
- arXiv
- CrossRef
- OpenAlex
- Europe PMC
- DOAJ
- BASE
|
- Semantic Scholar
- PubMed (NCBI)
- CORE
- Unpaywall
|
- Scopus (Elsevier)
- Web of Science
- IEEE Xplore
- Springer Nature
- ScienceDirect
- Dimensions
|
- TR Dizin
- DergiPark (OAI-PMH)
- YรK Tez Merkezi
|
---
## ๐ 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
```mermaid
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
| Source | How to Get Key | Cost |
|--------|---------------|------|
| Semantic Scholar | [semanticscholar.org/product/api](https://www.semanticscholar.org/product/api) | Free |
| PubMed (NCBI) | [ncbi.nlm.nih.gov/account](https://www.ncbi.nlm.nih.gov/account/) | Free |
| CORE | [core.ac.uk/services/api](https://core.ac.uk/services/api) | Free |
| Scopus | [dev.elsevier.com](https://dev.elsevier.com/) | Institutional |
| IEEE Xplore | [developer.ieee.org](https://developer.ieee.org/) | Paid |
| Springer | [dev.springernature.com](https://dev.springernature.com/) | Free tier |
| Dimensions | [dimensions.ai](https://www.dimensions.ai/scientometric-research/) | Free for research |
---
## ๐งช Development
```bash
# 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
| Module | Tests | What's Covered |
|--------|-------|----------------|
| Models | 15 | Paper, Author, SearchConfig, serialization |
| APA Formatter | 18 | In-text, references, ordering, Turkish chars |
| Config | 10 | Source availability, key management |
| Dedup | 9 | DOI match, fuzzy title, metadata richness |
| Analysis | 18 | Gap analysis, keywords, summarizer, citations |
| Visualization | 17 | Charts, tables, citation networks |
| Output | 12 | Section writer, DOCX generator |
| Search Base | 7 | Client lifecycle, safe_search |
| **Total** | **120** | **All passing โ
** |
---
## ๐ License
MIT ยฉ [ZaEyAsa](https://github.com/ZaEyAsa)
---
Built with โค๏ธ for researchers who deserve better tools.
If this helps your research, give it a โญ on GitHub!