Multi-Service MCP Server

A modular Model Context Protocol (MCP) server that provides scaled access to ArXiv research papers and Sequential Thinking tools for Claude Desktop applications.

🏗️ Architecture

This server uses a clean, modular architecture with tools organized in separate folders:

/Users/brandont/git/mpc/
├── server.py                           # Main server file
├── services/                           # Business logic
│   ├── arxiv_service.py               # ArXiv API operations
│   └── sequential_thinking_service.py  # Sequential thinking operations
├── tools/                              # MCP tools
│   ├── arxiv_tools.py                 # ArXiv MCP tools
│   └── sequential_thinking_tools.py   # Sequential thinking MCP tools
├── utils/                              # Shared components
│   └── __init__.py                    # Base classes & models
├── README.md                           # Documentation
├── QUICKSTART.md                      # Quick start guide
├── test_server.py                     # Test suite
├── Dockerfile                         # Docker configuration
├── docker-compose.yml                 # Docker Compose setup
├── setup-docker.sh                    # Docker setup script
├── run_mcp_docker.sh                  # Docker wrapper for Claude Desktop
├── claude_desktop_config_docker.json  # Docker config template
├── requirements.txt                   # Dependencies
└── .gitignore                         # Git ignore rules

🐳 Why Docker?

Docker provides several advantages for MCP servers:

✅ Benefits

• No Python Environment Setup: Eliminates virtual environment complexity

• Consistent Environment: Same behavior across all systems

• Easy Installation: Just docker build and you're ready

• Isolation: No conflicts with system Python packages

• Portability: Works on any system with Docker

• Easy Updates: Rebuild image to update dependencies

🚀 Features

• 8 ArXiv Tools: Search, details, recent papers, author papers, trending categories, advanced search, version support, phrase search

• 3 Sequential Thinking Tools: Dynamic problem-solving, thought revision, branching analysis

• Advanced Query Support: Boolean operators (AND, OR, ANDNOT), field-specific searches, phrase matching

• Enhanced Metadata: Journal references, DOI links, author comments, affiliations, primary categories

• Always Includes URLs: Every paper response includes both ArXiv abstract URL and PDF URL

• Version Support: Access specific versions of papers

• Docker-Based: Containerized deployment for easy setup

• Modular Design: Easy to add new services and tools

• Scalable Architecture: Clean separation of concerns

• Local Operation: Runs entirely on your local machine

• Claude Desktop Integration: Seamlessly integrates with Claude Desktop

📋 Available Tools

ArXiv Tools

1. search_arxiv - Search papers by query with sorting options

2. get_paper_details - Get detailed information about specific papers

3. get_recent_papers - Get recent papers from specific categories

4. get_papers_by_author - Get papers by specific authors

5. get_trending_categories - Get trending categories with paper counts

6. advanced_search - Multi-field search with Boolean operators and date ranges

7. get_paper_by_version - Get specific versions of papers

8. search_by_phrase - Search for exact phrases in titles, abstracts, or authors

Sequential Thinking Tools

1. sequential_thinking - Dynamic problem-solving through structured thoughts

2. get_thought_summary - Get summary of current thinking session

3. clear_thought_history - Clear thought history and branches

🛠️ Installation

Prerequisites

• Git (to clone the repository)

• Docker (for containerized installation)

🐳 Docker Installation

Quick Setup

1. Clone the repository:

   git clone https://github.com/brandont/arxiv-mcp-server.git
   cd arxiv-mcp-server

2. Run the Docker setup script:

   chmod +x setup-docker.sh
   ./setup-docker.sh

3. Test the Docker container:

   docker run --rm multi-service-mcp-server python test_server.py --test

Manual Setup

1. Clone the repository:

   git clone https://github.com/brandont/arxiv-mcp-server.git
   cd arxiv-mcp-server

2. Build the Docker image:

   docker build -t multi-service-mcp-server .

3. Test the installation:

   docker run --rm multi-service-mcp-server python test_server.py --test

🔧 Claude Desktop Integration

1. Locate your Claude Desktop configuration file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Add the Docker MCP server configuration:

   {
     "mcpServers": {
       "multi-service": {
         "command": "/path/to/your/multi-service-mcp-server/run_mcp_docker.sh",
         "args": []
       }
     }
   }

   Important: Replace /path/to/your/multi-service-mcp-server with the actual path where you cloned this repository

3. Alternative: Use the Docker config file:

   # Copy the Docker config and update the path
   cp claude_desktop_config_docker.json ~/Library/Application\ Support/Claude/claude_desktop_config.json
   # Then edit the file to add the correct path to run_mcp_docker.sh

4. Restart Claude Desktop to load the new MCP server.

Verification

Once configured, you can test the tools in Claude Desktop:

• "Search ArXiv for papers on machine learning"

• "Get details for paper 2301.00001"

• "Show me recent papers in cs.AI"

• "Get papers by author Geoffrey Hinton"

• "What are the trending categories this month?"

• "Advanced search: papers by Yann LeCun in cs.AI category from 2023"

• "Get version 2 of paper 2301.00001"

• "Search for exact phrase 'neural networks' in titles"

🔍 Advanced Search Features

Based on the ArXiv API documentation, this server supports:

Boolean Operators

• AND - Combine search terms

• OR - Find papers matching any term

• ANDNOT - Exclude certain terms

Field-Specific Searches

• au: - Author name (e.g., au:LeCun)

• ti: - Title keywords (e.g., ti:neural networks)

• abs: - Abstract keywords (e.g., abs:machine learning)

• cat: - ArXiv category (e.g., cat:cs.AI)

Phrase Matching

• Use double quotes for exact phrases: "deep learning"

Date Ranges

• Format: YYYYMMDD (e.g., 20230101)

• Range: submittedDate:[20230101 TO 20231231]

Example Advanced Queries

# Papers by LeCun about neural networks in AI category
au:LeCun AND ti:neural AND cat:cs.AI

# Recent papers excluding certain categories
submittedDate:[20240101 TO *] ANDNOT cat:cs.CV

# Exact phrase in abstract
abs:"transformer architecture"

🔧 Adding New Tools

The modular architecture makes adding new tools incredibly easy:

Step 1: Add Service Method

# services/arxiv_service.py
def get_papers_by_keyword(self, keyword: str) -> List[PaperInfo]:
    """Get papers containing a specific keyword."""
    # Implementation here
    pass

Step 2: Add Tool

# tools/arxiv_tools.py
@self.mcp.tool()
async def get_papers_by_keyword(keyword: str) -> str:
    """
    Get papers containing a specific keyword.
    
    Args:
        keyword: Keyword to search for
    
    Returns:
        JSON string containing matching papers
    """
    try:
        results = self.service.get_papers_by_keyword(keyword)
        return json.dumps([paper.model_dump() for paper in results], indent=2)
    except Exception as e:
        return json.dumps({"error": str(e)})

Step 3: Restart Server

That's it! The tool is automatically registered and available in Claude Desktop.

🏗️ Adding New Services

To add a completely new service (e.g., Weather, News):

Step 1: Create Service

# services/weather_service.py
from utils import BaseService

class WeatherService(BaseService):
    def get_name(self) -> str:
        return "Weather"
    
    def get_weather(self, city: str) -> dict:
        # Weather API logic
        pass

Step 2: Create Tool Provider

# tools/weather_tools.py
from utils import BaseToolProvider

class WeatherToolProvider(BaseToolProvider):
    def _register_tools(self):
        @self.mcp.tool()
        async def get_weather(city: str) -> str:
            """Get weather for a city."""
            result = self.service.get_weather(city)
            return json.dumps(result, indent=2)

Step 3: Register in Main Server

# server.py
from mcp.server.fastmcp import FastMCP
from services.arxiv_service import ArXivService
from services.weather_service import WeatherService
from tools.arxiv_tools import ArXivToolProvider
from tools.weather_tools import WeatherToolProvider

# Create the MCP server
mcp = FastMCP("Multi-Service MCP Server")

# Initialize services and tools
arxiv_service = ArXivService()
arxiv_tools = ArXivToolProvider(mcp, arxiv_service)

weather_service = WeatherService()
weather_tools = WeatherToolProvider(mcp, weather_service)

🧪 Testing

Run the test suite to verify everything works:

docker run --rm multi-service-mcp-server python test_server.py --test

🚨 Troubleshooting

Common Issues

1. Claude Desktop not recognizing the server:

   • Check that the path in the configuration file points to run_mcp_docker.sh

   • Ensure Claude Desktop is restarted after configuration changes

   • Verify the wrapper script is executable: chmod +x run_mcp_docker.sh

2. ArXiv API errors:

   • Check your internet connection and ArXiv accessibility

   • Some queries may fail due to ArXiv API limits

3. Docker issues:

   • Make sure Docker is installed and running: docker --version

   • For Docker daemon issues, restart Docker Desktop

   • Ensure the Docker image is built: docker build -t multi-service-mcp-server .

4. Permission errors on setup script:

   • Run chmod +x setup-docker.sh to make the script executable

Getting Help

• Check logs for detailed error information

• Run the test suite to verify functionality: docker run --rm multi-service-mcp-server python test_server.py --test

• Ensure Docker is properly installed and running

• Verify the Docker image is built correctly

📊 Technical Details

• Framework: Built using the official MCP Python SDK

• Architecture: Modular service-based design

• Deployment: Docker containerized

• ArXiv Access: Uses the arxiv Python library

• Transport: STDIO transport for Claude Desktop integration

• Tool Definition: Auto-generated from Python type hints and docstrings

📄 License

This project is open source and available under the MIT License.