ArXiv MCP Server - Docker Implementation

Production-Ready Containerized Research Assistant

🐳 DOCKER-FIRST: Production-ready containerized ArXiv research capabilities for AI assistants

🔬 RESEARCH-FOCUSED: Complete academic workflow - search, download, analyze papers seamlessly

Why This Docker Implementation?:

✅ Container Isolation: Secure, reproducible research environment
✅ Volume Persistence: Papers survive container restarts
✅ Production Grade: Multi-stage builds, optimized for performance
✅ Cross-Platform: Works on any Docker-enabled system
✅ MCP Compliant: Full Model Context Protocol 2024-11-05 support

🚀 Docker vs Traditional MCP: Why Container Matters

Feature	Traditional MCP	This Docker Implementation
Deployment	Local Python install	Single `docker run` command
Dependencies	Manual environment setup	All dependencies included
Isolation	Host system dependencies	Complete container isolation
Portability	Platform-specific setup	Works anywhere Docker runs
Storage	Local filesystem only	Persistent volume mounting
Scaling	Single instance	Easy multi-container deployment
Security	Host system access	Sandboxed execution

🎯 Key Docker Advantages

Zero Setup Friction: No Python environment conflicts or dependency issues
Reproducible Research: Same environment across different machines/platforms
Storage Persistence: Downloaded papers persist outside container lifecycle
Security Isolation: Research tools run in contained environment
Production Ready: Battle-tested Docker deployment patterns

The ArXiv MCP Server provides a bridge between AI assistants and arXiv's research repository through the Model Context Protocol (MCP). It allows AI models to search for papers and access their content in a programmatic way.

🤝 Contribute • 📝 Report Bug • 🐳 Docker Registry ✅

✨ Core Features

🔎 Paper Search: Query arXiv papers with filters for date ranges and categories
📄 Paper Access: Download and read paper content
📋 Paper Listing: View all downloaded papers
🗃️ Local Storage: Papers are saved locally for faster access
📝 Prompts: A Set of Research Prompts
🐳 Docker Ready: Official Docker MCP Registry integration with volume mounting

🚀 Quick Start with Docker

Option 1: Pre-built Docker Image (Recommended)

# Pull and run the latest image
docker run -i --rm \
  -v ./papers:/app/papers \
  jasonleinart/arxiv-mcp-server:latest

Option 2: Build from Source

# Clone this Docker-optimized repository
git clone https://github.com/jasonleinart/arxiv-mcp-server.git
cd arxiv-mcp-server

# Build the Docker image
docker build -t arxiv-mcp-server:local .

# Run your local build
docker run -i --rm \
  -v ./papers:/app/papers \
  arxiv-mcp-server:local

🔌 Claude Code Integration

Configure Claude Code to use the Docker MCP server by adding this to your claude_desktop_config.json:

{
  "mcpServers": {
    "arxiv-mcp-server-docker": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--name", "arxiv-mcp-server",
        "-v", "/path/to/your/papers:/app/papers",
        "jasonleinart/arxiv-mcp-server:latest"
      ],
      "env": {
        "ARXIV_STORAGE_PATH": "/app/papers"
      }
    }
  }
}

Important: Replace /path/to/your/papers with your desired local storage path.

🔧 Docker Deployment Options

Development Mode

# Mount source code for development
docker run -i --rm \
  -v $(pwd):/app \
  -v ./papers:/app/papers \
  python:3.11-slim \
  bash -c "cd /app && pip install -e . && python -m arxiv_mcp_server"

Production Mode with Custom Storage

# Run with specific storage location
docker run -i --rm \
  -v /your/research/papers:/app/papers \
  -e ARXIV_STORAGE_PATH=/app/papers \
  jasonleinart/arxiv-mcp-server:latest

Background Service Mode

# Run as background service
docker run -d \
  --name arxiv-mcp-service \
  -v ./papers:/app/papers \
  --restart unless-stopped \
  jasonleinart/arxiv-mcp-server:latest

🐳 Docker Architecture & Technical Details

Container Specifications

Base Image: Multi-stage build with python:3.11-slim-bookworm
Package Manager: UV for fast dependency resolution
Build Optimization: Bytecode compilation enabled for performance
Security: Non-root execution with minimal attack surface
Size: Optimized layers for efficient image distribution

Volume Mounting Requirements

Critical Path: Papers MUST be mounted to /app/papers inside container

# ✅ Correct - papers persist on host
docker run -v /host/papers:/app/papers jasonleinart/arxiv-mcp-server:latest

# ❌ Wrong - papers lost when container stops  
docker run jasonleinart/arxiv-mcp-server:latest

Environment Variables

Variable	Default	Purpose
`ARXIV_STORAGE_PATH`	`/app/papers`	Container storage location
`PYTHONUNBUFFERED`	`1`	Real-time logging output

Docker Compose Example

version: '3.8'
services:
  arxiv-mcp:
    image: jasonleinart/arxiv-mcp-server:latest
    volumes:
      - ./research-papers:/app/papers
    environment:
      - ARXIV_STORAGE_PATH=/app/papers
    restart: unless-stopped
    stdin_open: true
    tty: true

Multi-Platform Support

x86_64: Intel/AMD processors
ARM64: Apple Silicon (M1/M2/M3), AWS Graviton
Linux: Ubuntu, Debian, CentOS, Alpine
macOS: Docker Desktop integration
Windows: WSL2 backend support

Performance Characteristics

Startup Time: < 2 seconds cold start
Memory Usage: ~150MB baseline + paper storage
Network: Efficient arXiv API usage with caching
Storage: Papers stored as both PDF and optimized markdown

Production Deployment Tested

✅ Agent Validation Complete: Full tool functionality verified

Search operations: ✅ Successful arXiv queries
Download pipeline: ✅ PDF→Markdown conversion working
Volume persistence: ✅ Papers survive container restarts
MCP protocol: ✅ Full 2024-11-05 compliance
Claude Code integration: ✅ Seamless AI assistant connectivity

💡 Available Tools

The server provides four main tools designed to work together in research workflows:

1. Paper Search (`search_papers`)

🔍 Purpose: Find relevant research papers by topic, author, or category

When to use: Starting research, finding recent papers, exploring a field

# Basic search
result = await call_tool("search_papers", {
    "query": "transformer architecture"
})

# Advanced search with filters
result = await call_tool("search_papers", {
    "query": "attention mechanism neural networks",
    "max_results": 20,
    "date_from": "2023-01-01",
    "date_to": "2024-12-31",
    "categories": ["cs.AI", "cs.LG", "cs.CL"]
})

# Search by author
result = await call_tool("search_papers", {
    "query": "au:\"Vaswani, A\"",
    "max_results": 10
})

2. Paper Download (`download_paper`)

📥 Purpose: Download and convert papers to readable markdown format

When to use: After finding interesting papers, before reading full content

# Download a specific paper
result = await call_tool("download_paper", {
    "paper_id": "1706.03762"  # "Attention Is All You Need"
})

# Check download status
result = await call_tool("download_paper", {
    "paper_id": "1706.03762",
    "check_status": true
})

3. List Papers (`list_papers`)

📋 Purpose: View your local paper library

When to use: Check what papers you have, avoid re-downloading, browse collection

# See all downloaded papers
result = await call_tool("list_papers", {})

4. Read Paper (`read_paper`)

📖 Purpose: Access full text content of downloaded papers

When to use: Deep analysis, quotation, detailed study of methodology/results

# Read full paper content
result = await call_tool("read_paper", {
    "paper_id": "1706.03762"
})

🔄 Research Workflows

Complete Research Workflow

Here's how the tools work together in real research scenarios:

Scenario 1: Exploring a New Research Area

# Step 1: Search for recent papers in the field
search_result = await call_tool("search_papers", {
    "query": "large language model reasoning",
    "max_results": 15,
    "date_from": "2024-01-01",
    "categories": ["cs.AI", "cs.CL"]
})

# Step 2: Download promising papers
await call_tool("download_paper", {"paper_id": "2401.12345"})
await call_tool("download_paper", {"paper_id": "2402.67890"})

# Step 3: List your collection to confirm downloads
library = await call_tool("list_papers", {})

# Step 4: Read papers for detailed analysis
paper_content = await call_tool("read_paper", {"paper_id": "2401.12345"})

Scenario 2: Following Up on Specific Authors

# Find papers by specific researchers
result = await call_tool("search_papers", {
    "query": "au:\"Anthropic\" OR au:\"OpenAI\"",
    "max_results": 10,
    "date_from": "2023-06-01"
})

# Download the most relevant papers
for paper in result['papers'][:3]:
    await call_tool("download_paper", {"paper_id": paper['id']})

Scenario 3: Building a Literature Review

# Search multiple related topics
topics = [
    "transformer interpretability",
    "attention visualization",
    "neural network explainability"
]

for topic in topics:
    results = await call_tool("search_papers", {
        "query": topic,
        "max_results": 8,
        "date_from": "2022-01-01"
    })
    
    # Download top papers from each topic
    for paper in results['papers'][:2]:
        await call_tool("download_paper", {"paper_id": paper['id']})

# Review your complete collection
library = await call_tool("list_papers", {})

📝 Research Prompts

The server offers specialized prompts to help analyze academic papers:

Paper Analysis Prompt

A comprehensive workflow for analyzing academic papers that only requires a paper ID:

result = await call_prompt("deep-paper-analysis", {
    "paper_id": "2401.12345"
})

This prompt includes:

Detailed instructions for using available tools (list_papers, download_paper, read_paper, search_papers)
A systematic workflow for paper analysis
Comprehensive analysis structure covering:
- Executive summary
- Research context
- Methodology analysis
- Results evaluation
- Practical and theoretical implications
- Future research directions
- Broader impacts

⚙️ Configuration

Configure through environment variables:

Variable	Purpose	Default
`ARXIV_STORAGE_PATH`	Paper storage location	~/.arxiv-mcp-server/papers

📖 Advanced Usage Reference

Common ArXiv Categories

Category	Description	Use Cases
`cs.AI`	Artificial Intelligence	General AI research, reasoning, planning
`cs.LG`	Machine Learning	Neural networks, deep learning, training
`cs.CL`	Computation and Language	NLP, language models, text processing
`cs.CV`	Computer Vision	Image processing, visual recognition
`cs.RO`	Robotics	Autonomous systems, control theory
`stat.ML`	Machine Learning (Statistics)	Statistical learning theory, methods

Search Query Examples

Topic searches: "transformer architecture", "reinforcement learning" Author searches: "au:\"Hinton, Geoffrey\"", "au:OpenAI OR au:Anthropic" Title searches: "ti:\"Attention Is All You Need\"", "ti:BERT OR ti:GPT" Combined searches: "ti:transformer AND au:Vaswani", "abs:\"few-shot learning\" AND cat:cs.LG"

Local Model Best Practices

Use explicit workflows: Guide your model through Search → Download → List → Read → Analyze
Reference tool purposes: Mention why you're using each tool in your prompts
Check library first: Always use list_papers before downloading to avoid duplicates
Be specific with parameters: Use the exact formats shown in tool examples

🧪 Testing

Run the test suite:

python -m pytest

🤔 Docker vs Traditional MCP: When to Choose

Choose Docker Implementation When:

✅ Production deployment - Need reliable, consistent environments
✅ Team collaboration - Multiple developers need identical setups
✅ CI/CD integration - Automated testing and deployment pipelines
✅ Security isolation - Research tools need sandboxed execution
✅ Cross-platform - Supporting Windows, macOS, Linux users
✅ Scaling requirements - Multiple instances or load balancing
✅ Zero setup friction - Users want single-command deployment

Choose Traditional MCP When:

🔧 Development workflow - Active code modification and debugging
🔧 Custom integrations - Need to modify source code extensively
🔧 Resource constraints - Minimal overhead requirements
🔧 Direct filesystem - Need native host filesystem access patterns

Migration Path

Already using traditional MCP? Easy migration:

# Traditional MCP
uv tool run arxiv-mcp-server

# Equivalent Docker command  
docker run -i --rm -v ./papers:/app/papers jasonleinart/arxiv-mcp-server:latest

Your existing papers and workflows remain compatible!

🤖 Enhanced for Local Models & Docker MCP Gateway

Addressing Community Feedback: This Docker implementation specifically resolves issues with sparse tool descriptions that confuse local AI models.

🔍 Rich Tool Descriptions

Unlike minimal descriptions that cause local model confusion, each tool includes:

Purpose Statement: Clear explanation of what the tool does
Usage Context: When and why to use this tool
Parameter Guidance: Detailed input specifications with examples
Query Patterns: Built-in examples for search syntax and formatting
Integration Flow: How tools work together in research workflows

🎯 Local LLM Optimization Features

Docker MCP Gateway Ready: Seamless integration with local model deployments
Llama/Mistral/Local Model Tested: Verified compatibility with popular local LLMs
Context-Rich Responses: Tools provide detailed feedback to help models understand results
Error Handling: Clear error messages that local models can interpret and act on
Workflow Guidance: Tools suggest logical next steps in research processes

📋 Example: Enhanced Tool Descriptions

Before (Sparse): "search_papers": "Search arXiv papers"

After (Rich): "Search for academic research papers on arXiv.org using advanced filtering capabilities. This tool allows you to find papers by keywords, authors, categories, and date ranges. Use this when you need to discover relevant research papers on a specific topic, find papers by a particular author, or explore recent publications in a field..."

Impact: Local models now understand tool context and usage patterns, dramatically improving research workflow success rates.

🧪 Testing & Validation

This Docker implementation has been extensively tested:

Agent Testing: Validated with Claude Code using real research workflows
Multi-platform: Tested on macOS (Apple Silicon), Linux (x86_64)
Volume Persistence: Papers verified to survive container restarts
Performance: Sub-2-second startup, efficient memory usage
MCP Compliance: Full protocol 2024-11-05 compatibility

📄 License

Released under the Apache 2.0 License. See the LICENSE file for details.

🤝 Contributing

This is a Docker-focused fork optimizing ArXiv MCP for containerized deployment.

Original MCP Server: blazickjp/arxiv-mcp-server
This Docker Implementation: Focus on production container deployment

🐳 Containerized Research Excellence

Made for researchers, by developers who understand deployment complexity.

Name		Name	Last commit message	Last commit date
Latest commit History 90 Commits
.github		.github
src/arxiv_mcp_server		src/arxiv_mcp_server
tests		tests
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
.python-version		.python-version
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
final_integration_test.py		final_integration_test.py
pyproject.toml		pyproject.toml
smithery.yaml		smithery.yaml
test_async_workflow.py		test_async_workflow.py
test_docker_mcp.py		test_docker_mcp.py
test_mcp_protocol.py		test_mcp_protocol.py
test_mcp_server.py		test_mcp_server.py
test_storage_path.py		test_storage_path.py
uv.lock		uv.lock

License

jasonleinart/arxiv-mcp-server

Folders and files

Latest commit

History

Repository files navigation