Content
# 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.
Connection Info
You Might Also Like
awesome-mcp-servers
A collection of MCP servers.
git
A Model Context Protocol server for Git automation and interaction.
cc-switch
All-in-One Assistant for Claude Code, Codex & Gemini CLI across platforms.
TrendRadar
TrendRadar: Your hotspot assistant for real news in just 30 seconds.
oh-my-opencode
Background agents · Curated agents like oracle, librarians, frontend...
Appwrite
Build like a team of hundreds