botirk38/memcp

Memories.ai MCP Server

A type-safe Model Context Protocol (MCP) server that enables AI agents to interact with the Memories.ai API, providing comprehensive video upload, search, chat, and management capabilities for AI applications.

Overview

This MCP server bridges AI agents with the Memories.ai platform using a modular, type-safe architecture. It provides seamless integration with video upload from files or URLs, semantic search, AI-powered video chat, and comprehensive video library management through the standardized MCP interface.

Features

• 🎥 Video Upload - Upload videos from local files or URLs with MIME type detection
• 🔍 Semantic Search - Advanced semantic search with multiple search types (BY_VIDEO, BY_AUDIO, BY_CLIP)
• 💬 AI Video Chat - Streaming conversations about video content with session management
• 📊 Video Management - List, delete, and check video status with pagination and filtering
• 🔌 MCP Compatible - Full MCP specification compliance with tools, resources, and prompts
• 🔐 Secure Authentication - Flexible API key authentication (environment or query parameter)
• ⚡ Type-Safe Architecture - Built with TypeScript, Zod validation, and better-fetch
• 🚀 Streaming Responses - Real-time Server-Sent Events for chat functionality
• 🎯 Intelligent Prompts - Pre-built prompt templates for video analysis workflows

Prerequisites

• Node.js 18+ or Bun runtime (recommended)
• TypeScript 4.5+ for development
• A Memories.ai API key (Get one here)
• Claude Code or another MCP-compatible client

Installation

Quick Start

# Clone the repository
git clone https://github.com/yourusername/memories-ai-mcp.git
cd memcp

# Install dependencies (Bun recommended)
bun install

# Build the project
bun run build

Environment Setup

Create a .env file:

# Get your API key from: https://memories.ai/app/login (API Settings page)
MEMORIES_API_KEY=your_memories_ai_api_key_here

# Optional: Override the default API base URL
# MEMORIES_API_BASE_URL=https://api.memories.ai

# Optional: Set log level for debugging
# LOG_LEVEL=info

API Key Configuration

API keys can be provided in two ways:

1. Environment Variable (Recommended): Set MEMORIES_API_KEY in your .env file
2. Per-Tool Parameter: Include api_key as an optional parameter in individual tool calls

The per-tool parameter takes precedence over the environment variable, allowing for flexible multi-user scenarios.

Usage

Adding to Claude Code

Add the MCP server to Claude Code:

claude mcp add memories-ai --env MEMORIES_API_KEY=your_key_here -- node /path/to/memories-ai-mcp/dist/index.js

Or with the built executable:

claude mcp add memories-ai --env MEMORIES_API_KEY=your_key_here -- /path/to/memories-ai-mcp/dist/index.js

Available MCP Tools

The server exposes 8 comprehensive tools for AI agents:

upload-video-file

Upload a video file from local storage to Memories.ai

{
  "file_path": "/path/to/video.mp4",
  "unique_id": "user123",
  "callback": "https://callback.url/webhook",
  "video_name": "My Video"
}

Note: API key can be provided as optional api_key parameter or via environment variable

upload-video-url

Upload a video from a URL to Memories.ai

{
  "url": "https://example.com/video.mp4",
  "unique_id": "user123",
  "callback": "https://callback.url/webhook",
  "video_name": "My Video"
}

Note: API key can be provided as optional api_key parameter or via environment variable

search-videos

Search through uploaded videos using natural language with advanced options

{
  "query": "people talking about AI",
  "unique_id": "user123",
  "search_type": "BY_VIDEO",
  "folder_id": -1
}

Note: API key can be provided as optional api_key parameter or via environment variable

chat-with-videos

Have streaming AI conversations about one or more videos

{
  "video_nos": ["vid123", "vid456"],
  "prompt": "Summarize the main points discussed",
  "unique_id": "user123",
  "session_id": "session123"
}

Note: API key can be provided as optional api_key parameter or via environment variable

list-videos

Get a paginated list of uploaded videos with filtering options

{
  "unique_id": "user123",
  "page": 1,
  "size": 20,
  "video_name": "optional_filter",
  "video_no": "optional_id_filter",
  "status": "PARSE"
}

Note: API key can be provided as optional api_key parameter or via environment variable

delete-videos

Delete one or more videos from Memories.ai

{
  "video_nos": ["vid123", "vid456"],
  "unique_id": "user123"
}

Note: API key can be provided as optional api_key parameter or via environment variable

check-video-status

Check the processing status of uploaded videos

{
  "video_nos": ["vid123"],
  "unique_id": "user123"
}

Note: API key can be provided as optional api_key parameter or via environment variable

MCP Resources

memories://docs

Comprehensive API documentation and platform capabilities

• Complete endpoint reference
• Authentication methods
• Rate limits and best practices
• Troubleshooting guides

memories://video/{videoNo}

Detailed information about specific videos

• Video metadata and status
• Processing information
• Usage examples

MCP Prompts

analyze-video-content

Generate specialized prompts for video content analysis

• Analysis types: summary, emotions, objects, activities, transcript, technical, educational
• Detail levels: brief, detailed, comprehensive
• Focus areas: Customizable attention to specific aspects
• Context instructions: Specialized guidance per analysis type

build-search-query

Intelligent search query construction assistance

• Search approaches: visual, audio, combined content targeting
• Specificity levels: broad, specific, precise query scoping
• Context integration: Incorporates additional search parameters
• Query optimization: Balanced precision and recall strategies

video-workflow-helper

Step-by-step workflow guidance for common tasks

• Workflow types: upload, search, analyze, manage, integrate, troubleshoot
• Experience levels: beginner, intermediate, advanced guidance
• Best practices: Actionable recommendations and pitfall avoidance
• Tool integration: Specific MCP tool usage recommendations

Development

Project Structure

memcp/
├── src/
│   ├── index.ts              # Main MCP server entry point
│   ├── types/
│   │   └── memories.ts       # TypeScript types and Zod schemas
│   ├── clients/
│   │   └── memories.ts       # Type-safe Memories.ai API client
│   ├── tools/
│   │   ├── upload.ts         # Video upload tools
│   │   ├── search.ts         # Video search tools
│   │   ├── chat.ts           # Video chat tools
│   │   └── utils.ts          # Video management tools
│   ├── resources/
│   │   └── index.ts          # MCP resources (docs, video details)
│   ├── prompts/
│   │   └── index.ts          # MCP prompts for workflows
│   └── utils/
│       ├── api-key.ts        # API key management
│       └── mime-types.ts     # MIME type utilities
├── dist/                     # Built JavaScript files
├── memories-ai-docs/         # Local API documentation
├── package.json              # Project configuration
├── tsdown.config.ts          # Build configuration
├── tsconfig.json             # TypeScript configuration
├── biome.jsonc               # Code formatting configuration
└── .env                      # Environment variables

Available Scripts

• bun run dev - Start development server with watch mode
• bun run build - Build the project using tsdown
• bun run typecheck - Run TypeScript type checking
• bun run check - Run Biome linter and formatter
• bun run check:fix - Run Biome with auto-fix
• bun run start - Start the built server

Building

bun run build

This creates an executable dist/index.js file with proper shebang for direct execution.

API Reference

Memories.ai API Integration

The server integrates with Memories.ai API v1.2:

• Base URL: https://api.memories.ai
• Authentication: API key in Authorization header
• Supported Formats: h264, h265, vp9, hevc
• Languages: English (prompts and chat)

Error Handling

The server returns standardized MCP error responses:

• Authentication failures
• API rate limits
• Invalid parameters
• Network errors

Examples

Basic Video Upload

// AI agent can use this tool automatically
await upload_video_url({
  url: "https://example.com/presentation.mp4",
  unique_id: "user123",
  video_name: "Team Presentation"
});

Semantic Video Search

// Search for specific content in videos
const results = await search_videos({
  query: "discussion about quarterly goals",
  unique_id: "user123",
  search_type: "BY_VIDEO"
});

AI Video Chat

// Chat about video content
const response = await chat_with_videos({
  video_nos: ["vid123"],
  prompt: "What are the key action items mentioned?",
  unique_id: "user123"
});

Troubleshooting

Common Issues

MCP server fails to connect:

• Ensure the server builds successfully with bun run build
• Check that the API key is set correctly in environment variables
• Verify Node.js version compatibility

API authentication errors:

• Verify your Memories.ai API key is valid
• Check that the key is properly set in the MCP configuration

Video upload failures:

• Ensure video URLs are publicly accessible
• Check supported video formats (h264, h265, vp9, hevc)
• Verify rate limits aren't exceeded

Debug Mode

Run with debug logging:

claude --debug

Check MCP server logs in:

/Users/[username]/Library/Caches/claude-cli-nodejs/[project-path]/

Dependencies

Runtime Dependencies

• @modelcontextprotocol/sdk - MCP SDK for TypeScript
• @better-fetch/fetch - Type-safe HTTP client with schema validation
• zod - Runtime type validation and schema parsing

Development Dependencies

• @biomejs/biome - Fast formatter and linter
• tsdown - Modern TypeScript bundler
• typescript - TypeScript compiler

Architecture

Type Safety

• Comprehensive Types: Full TypeScript coverage with Zod runtime validation
• Schema-Based Client: Better-fetch integration with predefined API schemas
• Request/Response Validation: Automatic validation of all API interactions

Error Handling

• Graceful Degradation: Comprehensive error messages with troubleshooting guidance
• Retry Logic: Exponential backoff for transient failures
• Validation Errors: Clear feedback for invalid parameters

Performance

• Streaming Support: Server-Sent Events for real-time chat responses
• Efficient Uploads: Optimized file handling with MIME type detection
• Connection Pooling: Reusable HTTP connections with timeout management

License

MIT License - see file for details

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Learn More

• Memories.ai API Documentation
• Model Context Protocol Documentation
• Claude Code MCP Guide
• MCP TypeScript SDK