klavis

<div align="center">
  <picture>
    <img src="https://raw.githubusercontent.com/klavis-ai/klavis/main/static/klavis-ai.png" width="80">
  </picture>
</div>

<h1 align="center">Klavis AI - Open Source Model Context Protocol (MCP) Integrations for AI Applications</h1>

<div align="center">

[![Documentation](https://img.shields.io/badge/Documentation-📖-green)](https://docs.klavis.ai)
[![Website](https://img.shields.io/badge/Website-🌐-purple)](https://www.klavis.ai)
[![Discord](https://img.shields.io/badge/Discord-Join-7289DA?logo=discord&logoColor=white)](https://discord.gg/p7TuTEcssn)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![PyPI](https://img.shields.io/pypi/v/klavis.svg)](https://pypi.org/project/klavis/)
[![npm](https://img.shields.io/npm/v/klavis.svg)](https://www.npmjs.com/package/klavis)

</div>

## What is Klavis AI?

Klavis AI provides open-source Model Context Protocol (MCP) integrations designed to enhance AI applications.  Our API offers hosted, secure MCP servers, simplifying the process by eliminating the need for complex authentication management and extensive client-side coding.  MCP enables AI models to seamlessly interact with external tools and data sources, enriching their understanding and capabilities.

## ✨ Key Features

*   **🚀 Instant Integration:**  Quickly integrate with our Python and TypeScript SDKs, or directly via the REST API.
*   **🔐 Built-in Authentication:** Secure OAuth flows and API key management for seamless access to various services.
*   **⚡ Production-Ready:** Hosted infrastructure designed to scale and support millions of users.
*   **🛠️ 100+ Tools:** Access a wide range of integrations, including CRM, GSuite, GitHub, Slack, databases, and more.
*   **🌐 Multi-Platform:** Compatible with any LLM provider (OpenAI, Anthropic, Gemini, etc.) and AI agent framework (LangChain, LlamaIndex, CrewAI, AutoGen, etc.).
*   **🔧 Self-Hostable:** Open-source MCP servers that you can deploy and manage yourself.

## 🚀 Quick Start

### Installation

**Python**

```bash
pip install klavis

TypeScript/JavaScript

npm install klavis

Get Your API Key

Sign up at klavis.ai and create your API key. This key is required to authenticate with the Klavis hosted MCP servers.

Using the Klavis AI MCP Client

The Klavis AI client simplifies interaction with MCP servers. Here are examples of how to create and use MCP server instances.

Python Example

from klavis import Klavis
from klavis.types import McpServerName

klavis_client = Klavis(api_key="your-klavis-key")

# Create a YouTube MCP server instance
youtube_server = klavis_client.mcp_server.create_server_instance(
    server_name=McpServerName.YOUTUBE,
    user_id="user123",  # Replace with the user ID in your platform
    platform_name="MyApp"  # Replace with your platform's name
)

print(f"Server created: {youtube_server.server_url}")

TypeScript Example

import { KlavisClient, Klavis } from 'klavis';

const klavisClient = new KlavisClient({ apiKey: 'your-klavis-key' });

// Create a Gmail MCP server instance with OAuth
const gmailServer = await klavisClient.mcpServer.createServerInstance({
    serverName: Klavis.McpServerName.Gmail,
    userId: "user123",
    platformName: "MyApp"
});

// Gmail requires an OAuth flow.  Open the URL in a new window for the user to authenticate.
await window.open(gmailServer.oauthUrl);

Integrating MCP Functionality Directly (Function Calling)

This approach allows you to integrate Klavis AI MCP servers directly with your LLM provider or AI agent framework using function calling. This provides more control over the interaction between the LLM and the MCP server.

Python + OpenAI Example

import json
from openai import OpenAI
from klavis import Klavis
from klavis.types import McpServerName, ToolFormat

OPENAI_MODEL = "gpt-4o-mini"  # Or your preferred OpenAI model

openai_client = OpenAI(api_key="YOUR_OPENAI_API_KEY")
klavis_client = Klavis(api_key="YOUR_KLAVIS_API_KEY")

# Create a YouTube MCP server instance
youtube_server = klavis_client.mcp_server.create_server_instance(
    server_name=McpServerName.YOUTUBE,
    user_id="user123",
    platform_name="MyApp"
)

# Get available tools in OpenAI format
tools = klavis_client.mcp_server.list_tools(
    server_url=youtube_server.server_url,
    format=ToolFormat.OPENAI,
)

# Initial conversation
messages = [{"role": "user", "content": "Summarize this video: https://youtube.com/watch?v=..."}]

# First OpenAI call with function calling
response = openai_client.chat.completions.create(
    model=OPENAI_MODEL,
    messages=messages,
    tools=tools.tools
)

messages.append(response.choices[0].message)

# Handle tool calls
if response.choices[0].message.tool_calls:
    for tool_call in response.choices[0].message.tool_calls:
        result = klavis_client.mcp_server.call_tools(
            server_url=youtube_server.server_url,
            tool_name=tool_call.function.name,
            tool_args=json.loads(tool_call.function.arguments),
        )

        # Add tool result to conversation
        messages.append({
            "role": "tool",
            "tool_call_id": tool_call.id,
            "content": str(result)
        })

# Second OpenAI call to process tool results and generate final response
final_response = openai_client.chat.completions.create(
    model=OPENAI_MODEL,
    messages=messages
)

print(final_response.choices[0].message.content)

TypeScript + OpenAI Example

import OpenAI from 'openai';
import { KlavisClient, Klavis } from 'klavis';

// Constants
const OPENAI_MODEL = "gpt-4o-mini";

const EMAIL_RECIPIENT = "[email protected]";
const EMAIL_SUBJECT = "Hello from Klavis";
const EMAIL_BODY = "This email was sent using Klavis MCP Server!";

const openaiClient = new OpenAI({ apiKey: 'your-openai-key' });
const klavisClient = new KlavisClient({ apiKey: 'your-klavis-key' });

// Create server and get tools
const gmailServer = await klavisClient.mcpServer.createServerInstance({
    serverName: Klavis.McpServerName.Gmail,
    userId: "user123",
    platformName: "MyApp"
});

// Handle OAuth authentication for Gmail
if (gmailServer.oauthUrl) {
    console.log("Please complete OAuth authorization:", gmailServer.oauthUrl);
    await window.open(gmailServer.oauthUrl);
}

const tools = await klavisClient.mcpServer.listTools({
    serverUrl: gmailServer.serverUrl,
    format: Klavis.ToolFormat.Openai
});

// Initial conversation
const messages = [{
    role: "user",
    content: `Please send an email to ${EMAIL_RECIPIENT} with subject "${EMAIL_SUBJECT}" and body "${EMAIL_BODY}"`
}];

// First OpenAI call with function calling
const response = await openaiClient.chat.completions.create({
    model: OPENAI_MODEL,
    messages: messages,
    tools: tools.tools
});

messages.push(response.choices[0].message);

// Handle tool calls
if (response.choices[0].message.tool_calls) {
    for (const toolCall of response.choices[0].message.tool_calls) {
        const result = await klavisClient.mcpServer.callTools({
            serverUrl: gmailServer.serverUrl,
            toolName: toolCall.function.name,
            toolArgs: JSON