Research Server
A FastMCP-based Model Context Protocol (MCP) server for searching and managing academic papers from arXiv. This server demonstrates how to build MCP servers with tools, resources, and prompt templates.
Ask AI about Research Server
Powered by Claude Β· Grounded in docs
I know everything about Research Server. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Research MCP Server
A FastMCP-based Model Context Protocol (MCP) server for searching and managing academic papers from arXiv. This server demonstrates how to build MCP servers with tools, resources, and prompt templates.
Features
Tools
- search_papers: Search arXiv for papers on a specific topic and store their metadata locally
- extract_info: Retrieve detailed metadata for a specific paper by ID
Resources
- papers://folders: List all available research topic folders
- papers://{topic}: Get all papers for a specific research topic
Prompt Templates
- generate_search_prompt: Generate a structured prompt to guide research on a specific topic
Installation
-
Clone or download this project
-
Install dependencies:
pip install -r requirements.txt
Running the Server
Standalone Mode
Run the server directly:
python research_server.py
With Claude Desktop
Add the server to your Claude Desktop configuration:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Configuration:
{
"mcpServers": {
"research": {
"command": "python",
"args": [
"/absolute/path/to/research_server.py"
]
}
}
}
Replace /absolute/path/to/research_server.py with the actual path to your file.
Using the Python Client
Quick Start
Run the interactive demo:
python example_usage.py
This will show you an interactive menu with various examples.
Basic Client Usage
from research_client import ResearchClient
import asyncio
async def main():
client = ResearchClient()
# Connect to the server
await client.connect("./research_server.py")
# Search for papers
paper_ids = await client.search_papers("machine learning", max_results=5)
# Get detailed information
for paper_id in paper_ids:
await client.extract_info(paper_id)
# Browse topics
await client.get_folders()
# Close connection
await client.close()
asyncio.run(main())
Available Client Methods
Connection
connect(server_script_path)- Connect to the MCP serverclose()- Close the connection
Tools
search_papers(topic, max_results)- Search for papers on a topicextract_info(paper_id)- Get detailed information about a paper
Resources
get_folders()- List all research topic foldersget_topic_papers(topic)- Get all papers for a specific topic
Prompts
get_search_prompt(topic, num_papers)- Generate a search prompt template
Discovery
list_tools()- List all available toolslist_resources()- List all available resourceslist_prompts()- List all available prompt templates
Usage Examples
Example 1: Literature Review
from research_client import ResearchClient
import asyncio
async def literature_review():
client = ResearchClient()
await client.connect("./research_server.py")
# Search for papers
paper_ids = await client.search_papers("neural networks", max_results=5)
# Get details for each paper
for paper_id in paper_ids:
paper = await client.extract_info(paper_id)
print(f"Title: {paper['title']}")
print(f"Authors: {', '.join(paper['authors'])}")
await client.close()
asyncio.run(literature_review())
Example 2: Compare Topics
async def compare_topics():
client = ResearchClient()
await client.connect("./research_server.py")
topics = ["deep learning", "machine learning", "AI"]
for topic in topics:
await client.search_papers(topic, max_results=3)
# View all collected topics
folders = await client.get_folders()
await client.close()
asyncio.run(compare_topics())
Example 3: Interactive Menu (Recommended)
python example_usage.py
Select from:
- Literature Review - Search and analyze papers on a topic
- Compare Multiple Topics - Compare papers across different areas
- Deep Dive - Get comprehensive details on specific papers
- Browse Resources - Explore stored research data
- Generate Research Prompts - Create structured research prompts
- Run All Examples - Execute all examples sequentially
Using with Claude Desktop
When configured with Claude Desktop, you can use natural language:
- Search for papers:
Use the search_papers tool to find papers about "machine learning"
- Get paper details:
Use the extract_info tool to get details for paper ID "2301.12345"
- List all topics:
Show me the papers://folders resource
- View papers for a topic:
Show me papers://machine_learning
- Use prompt templates:
Use the generate_search_prompt template for "quantum computing" with 10 papers
Project Structure
MCP_server/
βββ research_server.py # Main MCP server implementation
βββ research_client.py # Python client for the MCP server
βββ example_usage.py # Interactive examples and demos
βββ requirements.txt # Python dependencies
βββ README.md # This file
βββ .gitignore # Git ignore rules
βββ .claude_mcp_config.json # Example MCP configuration
βββ data/
βββ papers/ # Storage for paper metadata
βββ topic1/ # Papers organized by topic
βββ topic2/
βββ ...
How It Works
Architecture
The project consists of two main components:
-
MCP Server (
research_server.py)- Built with FastMCP framework
- Exposes tools, resources, and prompt templates
- Handles arXiv API communication
- Manages local paper storage
-
Python Client (
research_client.py)- Connects to the MCP server via stdio
- Provides async methods to call tools and access resources
- Handles JSON parsing and formatting
- Manages connection lifecycle
Search Papers Tool
- Takes a topic and searches arXiv's API
- Parses XML responses to extract paper metadata
- Stores papers locally in topic-specific folders
- Returns list of paper IDs found
Extract Info Tool
- Searches local storage for a paper by ID
- Returns complete metadata including:
- Title and authors
- Abstract/summary
- Publication date
- PDF link
Resources
Resources provide read-only access to stored data:
- List all research topics you've explored
- View all papers within a specific topic
Prompt Templates
Reusable prompts that guide the AI to:
- Search for papers on a topic
- Extract and analyze paper details
- Provide structured summaries and recommendations
Client-Server Communication
- Client spawns server as subprocess
- Communication via JSON-RPC over stdio
- Client sends tool calls, resource requests, and prompt queries
- Server processes requests and returns structured responses
- Client parses and presents results
Data Storage
All paper metadata is stored locally in JSON format:
- Location:
data/papers/{topic}/{paper_id}.json - Format: JSON with title, authors, summary, publication date, and PDF link
API Reference
search_papers(topic: str, max_results: int = 5) -> List[str]
Search arXiv and store paper metadata.
Parameters:
topic: Research topic to search formax_results: Maximum number of papers to retrieve (default: 5)
Returns: List of paper IDs
extract_info(paper_id: str) -> str
Get metadata for a specific paper.
Parameters:
paper_id: arXiv paper ID (e.g., "2301.12345")
Returns: JSON string with paper metadata
Resource: papers://folders
Lists all topic folders with paper counts.
Returns: JSON with topics and counts
Resource: papers://{topic}
Get all papers for a specific topic.
Parameters:
topic: Topic name
Returns: JSON with all papers in the topic
generate_search_prompt(topic: str, num_papers: int = 5) -> str
Generate a research prompt.
Parameters:
topic: Research topicnum_papers: Number of papers to search for (default: 5)
Returns: Formatted prompt string
Troubleshooting
Server Issues
Server won't start
- Ensure all dependencies are installed:
pip install -r requirements.txt - Check Python version (3.8+ required)
- Verify the server script path is correct
Papers not found
- Make sure you've searched for papers first using
search_papers - Check that the
data/papersdirectory exists and has write permissions
arXiv API errors
- The arXiv API has rate limits; wait a few seconds between searches
- Check your internet connection
- Verify the arXiv API is accessible (try accessing http://export.arxiv.org/api/query in browser)
Client Issues
Connection errors
- Ensure the server script path in
connect()is correct and absolute - Check that Python is in your PATH
- Verify no other process is using the server
Async runtime errors
- Make sure you're running client code with
asyncio.run() - Don't mix async and sync code without proper await statements
JSON parsing errors
- Check that the server is returning valid JSON
- Ensure you're using the latest version of the client
- Try running the server standalone first to verify it works
Import errors
- Install all dependencies:
pip install -r requirements.txt - Verify you're in the correct directory
- Check Python path and virtual environment
Contributing
Feel free to extend this server with additional features:
- Support for other academic databases (PubMed, Semantic Scholar)
- Paper similarity analysis
- Citation graph visualization
- Automatic literature review generation
License
MIT License - feel free to use and modify for your projects.
