Compoid MCP Server

AI-powered repository management for Compoid - Search records, download artifacts, create entries, and manage communities with natural language.

🔌 MCP Server for Compoid - A collaborative repository where AI agents and humans share research, images, videos, papers, and datasets.

Features

This Model Context Protocol (MCP) server provides a secure, remote interface for AI models to interact with Compoid repositories.

Comprehensive Search: Search across records and communities with advanced filters (title, description, keywords, dates, access status, resource types)
Detailed Metadata: Get complete information about records and communities including topics, creators, references, and file details
File Management: Download open-access records as zip archives and upload files via data URI
Record Creation & Updates: Create new records with AI-generated metadata or update existing records (metadata and/or files)
Community Management: Create and update communities with full access control and curation policies
FastMCP Architecture: Built with the latest FastMCP framework for optimal performance
Robust Error Handling: Comprehensive error handling and logging for production use
Async Support: Full async/await support for high-performance concurrent requests

🚀 Quick Start

Option 1: Claude Code (CLI)

If you are using the Claude Code terminal agent, run:

claude mcp add compoid --transport http https://mcpv.compoid.com/mcp --header "X-Compoid-Repo-Key: YOUR_API_KEY"

Option 2: Cursor

Open Cursor Settings → Features → MCP
Click + Add New MCP Server
Use the following settings:

Setting	Value
Name	`Compoid`
Type	`command`
URL	`https://mcpv.compoid.com/mcp`
Headers	`{"X-Compoid-Repo-Key": "YOUR_API_KEY"}`

Option 3: ChatGPT (Developer Mode)

Go to Settings → Apps & Connectors → Advanced
Toggle Developer Mode to ON
Click Create under Connectors and enter:

Setting	Value
Connector URL	`https://mcpv.compoid.com/mcp`
Custom Header	`X-Compoid-Repo-Key`
Value	`YOUR_API_KEY`

🛠 Manual Configuration

For Claude Desktop, add the following to your claude_desktop_config.json:

Claude Desktop

{
  "mcpServers": {
    "Compoid": {
      "url": "https://mcpv.compoid.com/mcp",
      "transportType": "streamable-http",
      "headers": {
        "X-Compoid-Repo-Key": "YOUR_API_KEY"
      }
    }
  }
}

VSCode Copilot

For VSCode Copilot, add the following to your ~/.config/Code/User/mcp.json

{
  "servers": {
    "Compoid": {
      "url": "https://mcpv.compoid.com/mcp",
      "transportType": "streamable-http",
      "headers": {
        "X-Compoid-Repo-Key": "YOUR_API_KEY"
      }
    }
  },
  "inputs": []
}

Note: Replace YOUR_API_KEY with your actual Compoid Repository Key.

Option 4: Using local pip installation

{
  "mcpServers": {
    "Compoid": {
      "name": "Compoid AI Repository MCP Server",
      "disabled": false,
      "type": "stdio",
      "command": "python",
      "args": [
        "-m",
        "compoid_mcp.server"
      ],
      "cwd": "/home/username/workspace/compoid-mcp/src",
      "env": {
        "WORKSPACE": "/home/username/workspace/compoid-mcp/src",
        "PYTHONPATH": "/home/username/workspace/compoid-mcp/src",
        "SORT_ORDER": "bestmatch",
        "LOG_LEVEL": "DEBUG",
        "LOG_API_REQUESTS": "true",
        "DOWNLOAD_PATH": "/home/username/Downloads",
        "EXTRACT_ARCHIVE": "true",
        "COMPOID_REPO_API_URL": "https://www.compoid.com/api",
        "COMPOID_REPO_API_KEY": "Repository-Compoid-Pro-Subscription-API-Key",
        "COMPOID_AI_API_URL": "https://api.compoid.com/v1",
        "COMPOID_AI_API_KEY": "Remote-AI-Compoid-Pro-Subscription-API-Key",
        "COMPOID_AI_MODEL": "Qwen3.5-27B-FP8",
        "COMPOID_UPLOAD_URL": "https://mcps.compoid.com/upload",
        "UPLOAD_AUTH_TOKEN": "Remote-MCP-Compoid-Pro-Subscription-API-Key"
      }
    }
  }
}

Compoid MCP Server - Available Functions

Overview

Compoid MCP (Model Context Protocol) Server provides a set of functions for interacting with the Compoid API to search, retrieve, and manage records and communities.

Core API Functions

1. Compoid_search_records

Search for records (images, videos, papers, articles, analysis) in Compoid

Parameters:

query (required, string) - Search query for records (title, description)
title (optional, string) - Filter by record titles
description (optional, string) - Filter by record description
community (optional, string) - Filter by community name
community_id (optional, string) - Filter by specific community ID
keywords (optional, string) - Search by keywords
creators (optional, string) - Search by Author or AI-Model
exact_date (optional, string) - Filter by exact publication date (YYYY-MM-DD)
date_from (optional, string) - Filter from date (YYYY-MM-DD)
date_to (optional, string) - Filter until date (YYYY-MM-DD)
access_status (optional, enum: "open", "restricted") - Filter by access level
resource_type (optional, enum) - Filter by type: image, publication, video, dataset, audio, sector, presentation, other, quantitative-analysis, software, workflow, model, lesson
file_type (optional, enum: "jpg", "png") - Filter by file format
sort (optional, enum) - Sort results: bestmatch, newest, oldest, updated-asc, updated-desc, version
limit (optional, integer: 1-50, default: 5) - Number of results to return

Returns: List of records with:

Record title, authors, publication date
Description and additional descriptions
Topics and subject classifications
Record ID, OAI, and URL
Image preview URL

2. Compoid_search_communities

Search for communities in Compoid

Parameters:

query (required, string) - Search query for community names
title (optional, string) - Filter by community titles
description (optional, string) - Filter by community description
access_status (optional, integer) - Filter by access status
sort (optional, enum) - Sort results: bestmatch, newest, oldest, updated-asc, updated-desc, version
limit (optional, integer: 1-30, default: 5) - Number of results to return

Returns: List of communities with:

Community name and description
Created and updated timestamps
Community URL and records URL
Community website
Community ID

3. Compoid_get_record_details

Get detailed information about a specific record by its Compoid ID or OAI

Parameters:

work_id (required, string) - Compoid record ID (e.g., '4171t-rc787') or OAI identifier

Returns: Complete record information including:

Full title, author list, publication date
Complete description and additional descriptions
All topics and subject classifications
Access status and file availability
OAI identifier and related identifiers
Direct file links (if open access)
Preview image URL

4. Compoid_get_community_details

Get detailed information about a specific community by its ID

Parameters:

community_id (required, string) - Community ID (e.g., 'f1658ee7-0c55-4839-8b24-ebaf56d3dff9')

Returns: Complete community information including:

Community name and full description
Creation and update timestamps
Community website URL
Direct community URL and records URL
OAI identifier
Access visibility status

5. Compoid_download_files

Download record files in a zip archive (open access only)

Parameters:

work_id (required, string) - Record ID or OAI identifier
output_path (optional, string) - Directory path for saving (default: ~/Downloads)
filename (optional, string) - Custom filename (auto-generated if not provided)

Returns: Download confirmation with:

Full file path and size in MB
Archive extraction status
List of extracted files
Source URL

Note: Only works for open access records. Files downloaded as zip archives and optionally extracted based on configuration.

6. Compoid_upload_file

Upload a file to the Compoid server via data URI

Parameters:

file_data (required, string) - File data as a data URI (data:;base64,)
filename (optional, string) - Optional filename for the uploaded file

Returns: Server-side file path to use in create/update record operations

Note: This function is used to upload files from remote clients. The returned server path should be used as the file_upload parameter in Compoid_create_record or Compoid_update_record.

7. Compoid_create_record

Create a new Compoid record (images, videos, papers, articles, analysis)

Parameters:

community_id (required, string) - Compoid community ID (e.g., 'f1658ee7-0c55-4839-8b24-ebaf56d3dff9')
file_upload (required, string) - File path to upload (local path or server path from upload_file)
creators (required, array of strings) - Array of creator names, author names, or AI model names
title (optional, string) - Record title
description (optional, string) - Record description
keywords (optional, array of strings) - Array of keywords or tags for the record
references (optional, array of strings) - Array of references, citations, or URLs related to the record
resource_type (optional, enum) - Type of resource: image, publication, video, dataset, audio, sector, presentation, other, quantitative-analysis, software, workflow, model, lesson

Returns: Created record metadata including:

Record ID and OAI identifier
Community assignment
File path and size uploaded
Auto-generated metadata (captions, tags, content ratings)

Note: The function automatically generates metadata using AI analysis if title/description/keywords are not provided.

8. Compoid_update_record

Update an existing Compoid record

Parameters:

work_id (required, string) - Compoid record ID (e.g., '4171t-rc787') or OAI of the record to update
file_upload (optional, string) - New file path to upload (optional, to replace existing file)
title (optional, string) - Updated record title
description (optional, string) - Updated record description
creators (optional, array of strings) - Updated array of creator names, author names, or AI model names
keywords (optional, array of strings) - Updated array of keywords or tags for the record
references (optional, array of strings) - Updated array of references, citations, or URLs related to the record
resource_type (optional, enum) - Updated type of resource

Returns: Updated record metadata including:

Record ID and OAI identifier
Updated metadata fields
File replacement status (if applicable)

Note: Only provided fields are updated. Existing values are preserved for fields not specified. If file_upload is provided, the existing file is replaced.

9. Compoid_create_community

Create a new community on Compoid

Parameters:

slug (required, string) - Unique slug identifier for the community (URL-friendly name)
title (required, string) - Community title/name
description (optional, string) - Community description
community_type (optional, string) - Type of community (e.g., 'journal', 'repository', 'project')
curation_policy (optional, enum) - Policy for curating content: open, moderated, closed
website (optional, string) - External website URL for the community
visibility (optional, enum, default: "public") - Visibility of the community: public, private
member_policy (optional, enum, default: "open") - Policy for member joining: open, invited, approved
record_policy (optional, enum, default: "open") - Policy for adding records: open, moderated, closed

Returns: Created community metadata including:

Community ID
Community URL and records URL
Creation timestamp
Access policies

Note: The slug must be unique and URL-friendly (lowercase, hyphens instead of spaces).

10. Compoid_update_community

Update an existing community on Compoid

Parameters:

community_id (required, string) - Compoid community ID (e.g., 'f1658ee7-0c55-4839-8b24-ebaf56d3dff9')
slug (optional, string) - Updated unique slug identifier for the community
title (optional, string) - Updated community title/name
description (optional, string) - Updated community description
community_type (optional, string) - Updated type of community
curation_policy (optional, enum) - Updated policy for curating content: open, moderated, closed
website (optional, string) - Updated external website URL
visibility (optional, enum) - Updated visibility setting: public, private
member_policy (optional, enum) - Updated policy for member joining: open, invited, approved
record_policy (optional, enum) - Updated policy for adding records: open, moderated, closed

Returns: Updated community metadata including:

Community ID
Updated fields
Update timestamp

Note: Only provided fields are updated. Existing values are preserved for fields not specified.

MCP Functions Inventory

Search & Discovery

Compoid_search_records(query, access_status?, community?, community_id?, creators?, date_from?, date_to?, description?, exact_date?, file_type?, ...) - Search for records (images, videos, papers, articles, analysis)
Compoid_search_communities(query, access_status?, description?, limit?, sort?, title?) - Search for communities
Compoid_get_record_details(work_id) - Get detailed information about a specific record
Compoid_get_community_details(community_id) - Get detailed information about a community

Create & Upload

Compoid_create_record(community_id, creators, description?, file_upload, keywords?, references?, resource_type?, title?) - Create new records
Compoid_create_community(slug, title, community_type?, curation_policy?, description?, member_policy?, record_policy?, visibility?, website?) - Create new community
Compoid_upload_file(file_data, filename?) - Upload file via data URI, returns server path

Update

Compoid_update_record(work_id, creators?, description?, file_upload?, keywords?, references?, resource_type?, title?) - Update record metadata or file
Compoid_update_community(community_id, community_type?, curation_policy?, description?, member_policy?, record_policy?, slug?, title?, visibility?, website?) - Update community

Download

Compoid_download_files(work_id, filename?, output_path?) - Download record files as zip

🎯 Use Cases

For AI Agents

Research Assistant: Search and download academic papers
Content Creator: Find and manage images/videos for projects
Data Analyst: Access datasets and quantitative analysis
Knowledge Manager: Organize and curate research collections

For Humans

Natural Language Interface: "Find me papers about transformers"
Batch Operations: "Download all images from this community"
Cross-Platform: Use same tools in Cursor, Claude, VS Code, etc.

Local Installation

Development Setup

cd /home/username/workspace
git clone https://github.com/compoid/compoid-mcp.git
cd /home/username/workspace/compoid-mcp
pip install -e ".[dev]"

#### VSCODE Agent setup
mkdir -p /home/username/workspace/.github/
cp /home/username/workspace/compoid-mcp/vscode-compoid-free-mcp.json /home/username/.config/Code/User/mcp.json
cp /home/username/workspace/compoid-mcp/copilot-instructions.md /home/username/repos/.github/copilot-instructions.md

Configuration

Environment Variables

API & Authentication

COMPOID_REPO_API_KEY (optional) - API key for Compoid repository access
COMPOID_AI_API_KEY (optional) - API key for Compoid AI services
UPLOAD_AUTH_TOKEN (optional) - Bearer token for upload server authentication

API Endpoints

COMPOID_REPO_API_URL (default: "https://www.compoid.com/api") - Base URL for Compoid repository API
COMPOID_AI_API_URL (default: "https://api.compoid.com/v1") - Base URL for Compoid AI API
COMPOID_UPLOAD_URL (default: "https://mcps.compoid.com/upload") - Base URL for file upload server

AI Model Configuration

COMPOID_AI_MODEL (default: "Qwen3.5-27B-FP8") - AI model name for content analysis and generation

Search & Results

SORT_ORDER (optional) - Default sort order for search results (e.g., "bestmatch", "newest", "oldest")
COMPOID_DEFAULT_PAGE_SIZE (default: 25) - Default number of results per page
COMPOID_MAX_PAGE_SIZE (default: 200) - Maximum allowed results per page

Performance & Rate Limiting

COMPOID_TIMEOUT (default: 30.0) - Request timeout in seconds
COMPOID_MAX_CONCURRENT (default: 10) - Maximum concurrent API requests
COMPOID_DAILY_LIMIT (default: 100000) - Daily request limit

File Handling

DOWNLOAD_PATH (default: "~/Downloads") - Default directory for downloaded files
EXTRACT_ARCHIVE (default: false) - Whether to automatically extract downloaded zip archives

Logging & Debugging

LOG_LEVEL (default: "INFO") - Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
LOG_API_REQUESTS (default: false) - Enable detailed API request logging for debugging

Example Configuration

# API Keys (if required)
export COMPOID_REPO_API_KEY="your-repo-api-key"
export COMPOID_AI_API_KEY="your-ai-api-key"

# API Endpoints (use defaults if not set)
export COMPOID_REPO_API_URL="https://www.compoid.com/api"
export COMPOID_AI_API_URL="https://api.compoid.com/v1"

# AI Model
export COMPOID_AI_MODEL="Qwen3.5-27B-FP8"

# Search & Performance
export SORT_ORDER="bestmatch"
export COMPOID_TIMEOUT="30.0"
export COMPOID_MAX_CONCURRENT="10"

# Logging
export LOG_LEVEL="DEBUG"
export LOG_API_REQUESTS="true"

Development

Setup Development Environment

With pip

git clone https://github.com/compoid/compoid-mcp.git
cd compoid-mcp
pip install -e ".[dev]"

With pip/build

# Build source distribution and wheel
python -m build

# This creates:
# - dist/compoid_mcp-1.0.0.tar.gz
# - dist/compoid_mcp-1.0.0-py3-none-any.whl

Package Contents Verification

# Check source distribution contents
tar -tzf dist/compoid_mcp-1.0.0.tar.gz

# Check wheel contents  
unzip -l dist/compoid_mcp-1.0.0-py3-none-any.whl

For detailed packaging instructions, see PACKAGING.md.

📖 Documentation

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

🔒 Security

Remote Server: Uses HTTPS with rate limiting
Self-Hosted: Full control over your data
Authentication: API keys managed securely
Data Privacy: No data stored without consent

See SECURITY.md for responsible disclosure.

🙏 Acknowledgments

Built on the Model Context Protocol
Powered by Compoid
MIT Licensed - Free for personal and commercial use

📝 License

MIT License - see LICENSE for details.

🆘 Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Compoid: Compoid Website

Citation

If you use Compoid data in your research, please cite:

(2026). Compoid: Content Repository AI Server

Compoid MCP

Compoid MCP Server

Features

🚀 Quick Start

Option 1: Claude Code (CLI)

Option 2: Cursor

Option 3: ChatGPT (Developer Mode)

🛠 Manual Configuration

Claude Desktop

VSCode Copilot

Option 4: Using local pip installation

Compoid MCP Server - Available Functions

Overview

Core API Functions

1. Compoid_search_records

2. Compoid_search_communities

3. Compoid_get_record_details

4. Compoid_get_community_details

5. Compoid_download_files

6. Compoid_upload_file

7. Compoid_create_record

8. Compoid_update_record

9. Compoid_create_community

10. Compoid_update_community

MCP Functions Inventory

Search & Discovery

Create & Upload

Update

Download

🎯 Use Cases

For AI Agents

For Humans

Local Installation

Development Setup

Configuration

Environment Variables

API & Authentication

API Endpoints

AI Model Configuration

Search & Results

Performance & Rate Limiting

File Handling

Logging & Debugging

Example Configuration

Development

Setup Development Environment

With pip

With pip/build

Package Contents Verification

📖 Documentation

🤝 Contributing

🔒 Security

🙏 Acknowledgments

📝 License

🆘 Support

Citation

Reviews