Indico MCP Server

A Model Context Protocol (MCP) server for Indico, the event management system used at CERN and other research organizations worldwide. This server enables Claude Desktop and other MCP clients to search, retrieve, and interact with Indico events, categories, and data.

Quick Start

Installation via npx (Recommended)

The easiest way to use this server is with npx:

npx indico-mcp-server

Global Installation

npm install -g indico-mcp-server
indico-mcp-server

Claude Desktop Integration

Add this to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "indico": {
      "command": "npx",
      "args": ["indico-mcp-server"]
    }
  }
}

VS Code + GitHub Copilot Integration

Add this to your VS Code settings (.vscode/settings.json or user settings):

{
  "mcp.servers": {
    "indico": {
      "command": "npx",
      "args": ["indico-mcp-server"],
      "env": {
        "INDICO_BASE_URL": "https://indico.cern.ch",
        "INDICO_BEARER_TOKEN": "indp_your_token_here"
      }
    }
  }
}

Note: Store sensitive tokens in environment variables or VS Code secrets for better security.

Features

• 🔍 Event Search: Search for events by date, category, or keyword
• 📅 Event Details: Get comprehensive event information including contributions and materials
• 🏢 Category Management: Browse and search event categories
• 📄 File Access: List and access event attachments and materials
• 🔐 Secure Authentication: Modern Bearer token authentication
• 🌍 Multi-Instance Support: Works with any Indico instance (CERN, universities, etc.)

Configuration

The server supports two configuration methods:

Method 1: Environment Variables (VS Code/Copilot)

Set these environment variables or add them to your MCP server configuration:

• INDICO_BASE_URL - Your Indico instance URL (e.g., https://indico.cern.ch)
• INDICO_BEARER_TOKEN - Bearer token for authentication (optional for public data access)

Method 2: Runtime Configuration (Claude Desktop)

Use the configure tool through your MCP client:

{
  "base_url": "https://indico.cern.ch",
  "bearer_token": "indp_your_bearer_token_here"  // optional for public data
}

Authentication

Getting Your Bearer Token

The server uses modern Bearer token authentication to access Indico APIs. Bearer tokens are API keys that start with indp_ prefix.

Step-by-step guide:

1. Navigate to your Indico instance

   • Go to your Indico URL (e.g., https://indico.cern.ch)
   • Log in to your account

2. Access API settings

   • Click on your profile icon (top-right corner)
   • Select Preferences
   • Go to the API tab

3. Create a new token

   • Click Create token
   • Give it a descriptive name (e.g., "MCP Server Access")
   • Select required scopes:
     • ✅ read:legacy_api - Required for searching and reading events
     • ✅ write:legacy_api - Optional, only if you need to create events or book rooms
     • ✅ read:user - Optional, for accessing user information

4. Copy your token

   • Your token will start with indp_
   • Copy it immediately - you won't be able to see it again
   • Store it securely in your configuration

Public vs Authenticated Access

Public Access (No Token Required):

• Search for public events
• Browse public categories
• View public event details
• Access publicly available files

Authenticated Access (Token Required):

• Access private/restricted events
• Download protected files
• Create new events
• Book rooms
• Access user-specific information

Token Security

⚠️ Important Security Notes:

• Never commit tokens to version control
• Store tokens in environment variables or secure configuration files
• Tokens have the same access level as your user account
• Revoke tokens immediately if compromised
• Create separate tokens for different applications
• Set appropriate scopes - only grant permissions you need

Example Configurations

For public data access only (no token needed):

{
  "mcpServers": {
    "indico": {
      "command": "npx",
      "args": ["indico-mcp-server"],
      "env": {
        "INDICO_BASE_URL": "https://indico.cern.ch"
      }
    }
  }
}

For authenticated access:

{
  "mcpServers": {
    "indico": {
      "command": "npx",
      "args": ["indico-mcp-server"],
      "env": {
        "INDICO_BASE_URL": "https://indico.cern.ch",
        "INDICO_BEARER_TOKEN": "indp_your_token_here"
      }
    }
  }
}

Available Tools

Core Tools

• configure - Set up server connection and authentication
• get_user_info - Get current user information
• search_events - Search for events in specific categories
• search_events_by_term - Search events by keyword across all categories
• get_event_details - Get detailed information about a specific event
• search_categories - Search and browse event categories
• get_event_contributions - Get contributions/presentations for an event
• get_files - List all files and attachments for an event

Usage Examples

Search for events

// Search in a specific category
search_events({
  "category_id": "4",
  "from_date": "2024-01-01",
  "to_date": "2024-12-31",
  "limit": 10
})

// Search by keyword
search_events_by_term({
  "search_term": "machine learning",
  "limit": 20
})

Get event details

get_event_details({
  "event_id": "1234567"
})

Browse categories

search_categories({
  "search_term": "physics"
})

Development

Building from Source

git clone https://gitlab.cern.ch/epa-wp8-automate-equipment/project-astra/indico-mcp.git
cd indico-mcp
npm install
npm run build

Running in Development Mode

npm run dev

Testing

npm test

API Coverage

This server implements the most commonly used Indico HTTP API endpoints:

• Export API: /export/categ/{id}.json, /export/event/{id}.json
• User API: /api/user/
• Search: Full-text search across events and categories
• File Access: Event materials and attachments

Supported Indico Instances

This server works with any Indico instance, including:

• CERN Indico - The original instance at CERN
• UN Indico - United Nations events
• University instances - Many universities run their own Indico servers
• Private instances - Any organization using Indico

Requirements

• Node.js 18.0.0 or higher
• Valid Indico API credentials
• Network access to your Indico instance

Security

• All API credentials are handled securely and never logged
• HTTPS is enforced for all API communications
• Authentication tokens are validated on each request
• No credentials are stored permanently - configuration is in-memory only

Troubleshooting

Common Issues

1. "Server not configured" - Run the configure tool first with your Indico credentials
2. "Authentication failed" - Check your API token and ensure it has the required scopes
3. "Event not found" - Verify the event ID and check if you have permission to access it
4. "Network error" - Ensure your Indico instance URL is correct and accessible

Debug Mode

Set the DEBUG environment variable for verbose logging:

DEBUG=indico-mcp-server npx indico-mcp-server

Contributing

Contributions are welcome! Please see our Contributing Guide for details.

Reporting Issues

If you encounter any issues, please report them on our GitLab Issues page.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Related Projects

• Indico - The event management system this server interfaces with
• Model Context Protocol - The protocol this server implements
• Claude Desktop - AI assistant that can use this server

Changelog

See CHANGELOG.md for a list of changes and version history.