indico-mcp

# Indico MCP Server [](https://badge.fury.io/js/indico-mcp-server) A Model Context Protocol (MCP) server for [Indico](https://getindico.io/), 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: ```bash npx indico-mcp-server ``` ### Global Installation ```bash 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` ```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): ```json { "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: ```javascript { "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):** ```json { "mcpServers": { "indico": { "command": "npx", "args": ["indico-mcp-server"], "env": { "INDICO_BASE_URL": "https://indico.cern.ch" } } } } ``` **For authenticated access:** ```json { "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 ```javascript // 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 ```javascript get_event_details({ "event_id": "1234567" }) ``` #### Browse categories ```javascript search_categories({ "search_term": "physics" }) ``` ## Development ### Building from Source ```bash 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 ```bash npm run dev ``` ### Testing ```bash 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](https://indico.cern.ch) - The original instance at CERN - [UN Indico](https://indico.un.org) - 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: ```bash DEBUG=indico-mcp-server npx indico-mcp-server ``` ## Contributing Contributions are welcome! Please see our [Contributing Guide](CONTRIBUTING.md) for details. ### Reporting Issues If you encounter any issues, please report them on our [GitLab Issues](https://gitlab.cern.ch/epa-wp8-automate-equipment/project-astra/indico-mcp/-/issues) page. ## License This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. ## Related Projects - [Indico](https://getindico.io/) - The event management system this server interfaces with - [Model Context Protocol](https://modelcontextprotocol.io/) - The protocol this server implements - [Claude Desktop](https://claude.ai/) - AI assistant that can use this server ## Changelog See [CHANGELOG.md](CHANGELOG.md) for a list of changes and version history.