Overview
🎓 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
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:
📋 Windows — %APPDATA%\Claude\claude_desktop_config.json
{
"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"
}
}
}
}
📋 macOS — ~/Library/Application Support/Claude/claude_desktop_config.json
{
"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
| 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 |
|---|---|---|---|
|
|
|
|
🏗 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]
- Search — Queries up to 18 databases in parallel, routes by field (medicine → PubMed, CS → Semantic Scholar)
- Deduplicate — Removes duplicates via exact DOI + fuzzy title matching (92% threshold)
- Analyze — Identifies themes, gaps, trends, and extracts keywords
- Visualize — Generates charts, tables, and citation networks
- Format — Applies APA 7th edition rules for citations and references
- Output — Assembles everything into a formatted
.docxmanuscript
📖 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:
- Search across available databases
- Deduplicate and rank results
- Analyze themes and identify gaps
- Generate formatted citations
- Write a structured section with proper references
🔑 API Key Setup
| Source | How to Get Key | Cost |
|---|---|---|
| Semantic Scholar | semanticscholar.org/product/api | Free |
| PubMed (NCBI) | ncbi.nlm.nih.gov/account | Free |
| CORE | core.ac.uk/services/api | Free |
| Scopus | dev.elsevier.com | Institutional |
| IEEE Xplore | developer.ieee.org | Paid |
| Springer | dev.springernature.com | Free tier |
| Dimensions | dimensions.ai | Free for research |
🧪 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
| 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
Built with ❤️ for researchers who deserve better tools.
If this helps your research, give it a ⭐ on GitHub!
Server Config
{
"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"
}
}
}
}Project Info
Created At
3 months agoUpdated At
3 months agoAuthor Name
zaeyasaStar
-Language
-License
-Tags
Recommend Servers
View AllAmap Maps
@amap
高德地图官方 MCP Server
a year ago
Mcp Server Chatsum
@chatmcp
summarize chat message
typescript
a year ago
Gpt Scrambler
2 days ago