Content
# Academic Search MCP
Local stdio MCP Server, built specifically for paper search in the field of Robotics + Reinforcement Learning (Robotics + RL). Supports searching by keywords, time range, author, journal/conference, viewing citation counts, impact factors, h-index, and more, as well as retrieving abstracts, DOIs, and PDF links.
## Data Sources
| API | Purpose | Authentication |
|-----|------|------|
| [Semantic Scholar](https://api.semanticscholar.org/) | Paper search, details, citations, authors | Optional `S2_API_KEY` |
| [arXiv](https://arxiv.org/help/api/) | Preprint search, direct PDF link | Not required |
| [OpenAlex](https://docs.openalex.org/) | Journal/conference impact factors, h-index | Requires `OPENALEX_API_KEY` (free) |
## Prerequisites
- Node.js 18+
- OpenAlex free API Key: [openalex.org/settings/api](https://openalex.org/settings/api) (register in 30 seconds)
- Semantic Scholar API Key (optional, to increase rate to 1req/sec): [application address](https://www.semanticscholar.org/product/api#api-key-form)
## Installation
```bash
git clone https://github.com/Linductor-alkaid/academic-search-mcp.git
cd academic-search-mcp
npm install
npm run build
```
## Claude Desktop Configuration
Merge the following content into Claude Desktop's `claude_desktop_config.json`:
```json
{
"mcpServers": {
"academic-search": {
"command": "node",
"args": ["/path/to/academic-search-mcp/dist/index.js"],
"env": {
"OPENALEX_API_KEY": "your_openalex_key_here",
"S2_API_KEY": "your_s2_key_here"
}
}
}
}
```
> Use forward slashes `/` or double backslashes `\\` for Windows paths.
## Tool List
### `search_papers`
Search for papers through Semantic Scholar.
| Parameter | Type | Default | Description |
|------|------|--------|------|
| `query` | string | Required | Search keywords |
| `year_start` | number | — | Start year |
| `year_end` | number | — | End year |
| `fields_of_study` | string | `"Computer Science"` | Field of study |
| `limit` | number | `20` | Number of results (1-100) |
Returns: title, authors, year, abstract (first 300 characters), citation_count, venue, DOI/arXiv ID
---
### `get_paper_details`
Get complete paper information, including references and cited papers.
| Parameter | Type | Description |
|------|------|------|
| `paper_id` | string | S2ID, `DOI:10.xxx`, or `ARXIV:2301.xxxxx` |
Returns: complete abstract, PDF link, references (first 20), cited papers (first 20, sorted by citations)
---
### `search_arxiv_papers`
Search for arXiv preprints, supporting category filtering.
| Parameter | Type | Default | Description |
|------|------|--------|------|
| `query` | string | Required | Search keywords |
| `categories` | string[] | `["cs.RO"]` | arXiv categories, e.g., `cs.RO`, `cs.LG`, `eess.SY` |
| `max_results` | number | `20` | Maximum number of results |
| `date_from` | string | — | Start date, format `YYYY-MM-DD` |
Returns: arXiv ID, title, authors, abstract, published_date, pdf_url, categories
---
### `get_journal_metrics`
Query journal or conference impact metrics through OpenAlex.
| Parameter | Type | Description |
|------|------|------|
| `venue_name` | string | Journal/conference name, e.g., `"ICRA"`, `"Nature Robotics"` |
Returns: impact_factor (2yr), h_index, works_count, cited_by_count, homepage_url
---
### `get_author_info`
Query author's academic metrics and representative works.
| Parameter | Type | Description |
|------|------|------|
| `author_name` | string | Author name (choose one with `author_id`) |
| `author_id` | string | Semantic Scholar author ID |
Returns: h_index, citation_count, paper_count, affiliations, representative works (first 10, sorted by citations)
---
### `get_citations`
Get papers that cite a specified paper.
| Parameter | Type | Default | Description |
|------|------|--------|------|
| `paper_id` | string | Required | S2ID, `DOI:10.xxx`, or `ARXIV:2301.xxxxx` |
| `limit` | number | `20` | Number of results (1-100) |
Returns: list of papers that cite the specified paper, sorted by citation_count
## Usage Examples
**Search recent robotics and reinforcement learning papers:**
> Help me search for highly cited papers on "robot manipulation reinforcement learning" from 2023-2025.
**View ICRA conference metrics:**
> What is the impact factor and h-index of the ICRA conference?
**Find all citations of a paper:**
> Help me find the latest highly cited papers that cite "Soft Actor-Critic".
**Query author information:**
> What is Sergey Levine's h-index, and what are his most influential papers?
**Search latest arXiv preprints:**
> Search for papers on "diffusion policy" in cs.RO and cs.LG categories since 2024.
## Paper ID Format Quick Reference
All tools that accept `paper_id` support the following 5 formats, **automatically normalized** to Semantic Scholar's internal representation:
| Input | Normalized to | Notes |
|--------|-------------|------|
| `2402.18294` | `ARXIV:2402.18294` | Bare arXiv ID (YYMM.NNNNN) |
| `ARXIV:2402.18294` | `ARXIV:2402.18294` | Case-insensitive |
| `10.1109/IROS.2024.10801451` | `DOI:10.1109/...` | Bare DOI |
| `DOI:10.1109/...` | `DOI:10.1109/...` | |
| 40-character hex (e.g., `9e1c2411c873a95843c4ce670fb53569c65059d6`) | Original | S2 paperId |
Unrecognized formats return a 400 error with a list of supported formats.
## Paper Details Output Volume Control
`get_paper_details` includes references and cited papers by default (10 each, approximately 30-60KB). For larger outputs:
| Parameter | Type | Default | Effect |
|------|------|------|------|
| `include_references` | bool | `true` | Include references list |
| `include_citations` | bool | `true` | Include cited papers list |
| `references_limit` | 0-100 | `10` | Number of references |
| `citations_limit` | 0-100 | `10` | Number of cited papers |
Minimal call example (only abstract and metadata):
```
get_paper_details(paper_id="2402.18294", include_references=false, include_citations=false)
```
Additionally, `formatResponse` has two layers of truncation (single string field: 2000 chars, JSON total length: 50000 chars), exceeding which will be truncated with a hint.
## Author Disambiguation
`get_author_info(author_name=...)` now returns **top 5 candidate authors**, each with `author_id`, institution, h-index, and citation count. Useful for Chinese/pinyin name ambiguity:
- Primary information remains the first candidate (original behavior)
- Additional "search candidates" list + ⚠️ hint at the end
- Use `author_id="..."` to retry and precisely specify the author
## arXiv Category Default
`search_arxiv_papers` defaults to `categories=["cs.RO"]` (**robotics only**). For cross-category search:
```
search_arxiv_papers(query="...", categories=["cs.RO", "cs.LG", "eess.SY"])
```
## OpenAlex Field Notes
⚠️ `get_journal_metrics` returns '2yr mean citedness' **not** JCR Impact Factor. OpenAlex's own metric.
- **Conferences (type=conference)**: no such field, marked N/A; refer to h-index and total citations
- **Journals (type=journal)**: referable, but different from JCR IF (different scope)
## Abstract Length Customization
`search_papers` and `search_arxiv_papers` truncate abstracts to 300 characters by default. Set larger:
```
search_papers(query="...", abstract_chars=2000)
```
`abstract_chars=0` means no truncation.
## v1.0.0 → v1.1.0 Migration Guide
v1.1.0 includes **1 breaking change** and **1 behavioral default change**. Other changes are optional and backward-compatible.
### Breaking Change: `VenueMetrics.impactFactor` Renamed
OpenAlex's `summary_stats['2yr_mean_citedness']` **not** JCR Impact Factor. Old name `impactFactor` was misleading.
```diff
// Old (v1.0.0)
const venue = parseJsonDump(getJournalMetrics("ICRA"));
console.log(venue[0].impactFactor); // → undefined (field removed)
// New (v1.1.0)
const venue = parseJsonDump(getJournalMetrics("ICRA"));
console.log(venue[0].twoYearMeanCitedness); // → null (conference) or value (journal)
```
**Migration steps**:
- If your code accesses `v.impactFactor`, change to `v.twoYearMeanCitedness`
- If relying on `impactFactor !== null` to judge "this is a journal", change to `v.type !== "conference"`
- Conferences (type=conference) now return `twoYearMeanCitedness: null`, markdown block displays `N/A (conference has no such metric; refer to h-index / total citations)`
### Behavioral Change: `get_paper_details` Default Count 20 → 10
Old versions included 20 references and citations each (approximately 134K chars). v1.1.0 defaults to 10/10 (about 30-60K), safer.
```diff
// Old (v1.0.0)
get_paper_details(paper_id="ARXIV:2402.18294")
→ returns references × 20, citations × 20
// New (v1.1.0) — default behavior changed
get_paper_details(paper_id="ARXIV:2402.18294")
→ returns references × 10, citations × 10
```
**Migration steps** (if you need the complete list):
- For old behavior: `get_paper_details(paper_id="...", references_limit=20, citations_limit=20)`
- For minimal output: `get_paper_details(paper_id="...", include_references=false, include_citations=false)`
### New Optional Parameters (non-breaking, backward-compatible)
| Tool | New parameter | Old caller needs to change? |
|------|--------|----------------|
| `get_paper_details` | `include_references`, `include_citations`, `references_limit`, `citations_limit` | ❌ No |
| `get_citations` / `get_paper_details` | `paper_id` now accepts bare arXiv ID / bare DOI | ❌ No (old formats still work) |
| `search_papers` / `search_arxiv_papers` | `abstract_chars` | ❌ No |
| `get_author_info` | name search now returns top-5 candidate list | ❌ No (primary info remains the same) |
### Upgrade Suggestions
```bash
cd academic-search-mcp
git pull origin master
npm install # No new dependencies, but recommended
npm run build
```
Claude Desktop configuration remains unchanged (no new env vars, no schema incompatibility). Restart Claude Desktop to apply the new version.
---
## Rate Limiting
- **Semantic Scholar (no key)**: 100 req/5min, 429 automatically retries with exponential backoff (1s→2s→4s)
- **Semantic Scholar (with key)**: 1 req/sec, basically unlimited
- **arXiv**: no hard limit, recommend 3s interval
- **OpenAlex (with key)**: $1/day budget, sufficient for daily use
## Development
```bash
npm run build # Compile TypeScript
npm run dev # Watch mode compilation
```
MCP Inspector debugging (need to install globally or use npx):
```bash
OPENALEX_API_KEY=xxx node dist/index.js
```
