Akave MCP Server

A Model Context Protocol (MCP) server that enables AI models to interact with Akave's S3-compatible storage. This server provides a set of tools for managing your Akave storage buckets and objects through AI models like Claude and local LLMs.

What is MCP?

The Model Context Protocol (MCP) is an open protocol that standardizes how applications provide context to Large Language Models (LLMs). Think of MCP like a USB-C port for AI applications - it provides a standardized way to connect AI models to different data sources and tools.

Features

List and manage buckets
Upload, download, and manage objects
Generate signed URLs for secure access
Support for both Claude and local LLMs (via Ollama)
Simple configuration through JSON

Prerequisites

Node.js 16+
Access to an Akave account with:
- Access Key ID
- Secret Access Key
- Endpoint URL
For local LLM support:
- Go 1.23 or later
- Ollama installed

Quick Start

Create a configuration file (e.g., mcp.json):

{
  "mcpServers": {
    "akave": {
      "command": "npx",
      "args": [
        "-y",
        "akave-mcp-js"
      ],
      "env": {
        "AKAVE_ACCESS_KEY_ID": "your_access_key",
        "AKAVE_SECRET_ACCESS_KEY": "your_secret_key",
        "AKAVE_ENDPOINT_URL": "your_endpoint_url"
      }
    }
  }
}

Usage with Claude Desktop

Download and install Claude for Desktop (macOS or Windows)
Open Claude Desktop Settings:
- Click on the Claude menu
- Select "Settings..."
- Click on "Developer" in the left-hand bar
- Click on "Edit Config"
This will create/update the configuration file at:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
Add the Akave MCP server configuration to the file:

{
  "mcpServers": {
    "akave": {
      "command": "npx",
      "args": [
        "-y",
        "akave-mcp-js"
      ],
      "env": {
        "AKAVE_ACCESS_KEY_ID": "your_access_key",
        "AKAVE_SECRET_ACCESS_KEY": "your_secret_key",
        "AKAVE_ENDPOINT_URL": "your_endpoint_url"
      }
    }
  }
}

Restart Claude Desktop
You should see a slider icon in the bottom left corner of the input box. Click it to see the available Akave tools.

Usage with Local LLMs (Ollama)

Install MCPHost:

go install github.com/mark3labs/mcphost@latest

Start MCPHost with your preferred model using the same configuration file:

# Using default config location
mcphost -m ollama:mistral

# Or specify a custom config file
mcphost -m ollama:mistral --config /path/to/your/mcp.json

# For debugging
mcphost --debug -m ollama:mistral --config /path/to/your/mcp.json

You can use any Ollama model, for example:

ollama:mistral
ollama:qwen2.5
ollama:llama2

Available Tools

The server provides the following MCP tools:

list_buckets: List all buckets in your Akave storage
list_objects: List objects in a bucket with optional prefix filtering
get_object: Read object contents from a bucket
put_object: Write a new object to a bucket
get_signed_url: Generate a signed URL for secure access to an object
update_object: Update an existing object
delete_object: Delete an object from a bucket
copy_object: Copy an object to another location
create_bucket: Create a new bucket
delete_bucket: Delete a bucket
get_bucket_location: Get the region/location of a bucket
list_object_versions: List all versions of objects (if versioning enabled)

Example Usage

Listing Buckets

# The AI model will automatically use the list_buckets tool
List all my buckets

Reading a File

# The AI model will use the get_object tool
Read the file 'example.md' from bucket 'my-bucket'

Uploading a File

# The AI model will use the put_object tool
Upload the content 'Hello World' to 'greeting.txt' in bucket 'my-bucket'

Troubleshooting

Common Issues

Connection Refused
- Ensure your Akave credentials are correct in the MCP configuration
- Check if the endpoint URL is accessible
- Verify your network connection
File Reading Issues
- For markdown files, ensure proper encoding
- For binary files, use appropriate tools
- Check file permissions
Local LLM Issues
- Ensure Ollama is running
- Verify model compatibility
- Check MCPHost configuration
- Use --debug flag for detailed logs
Claude Desktop Issues
- Check logs at:
  - macOS: ~/Library/Logs/Claude/mcp*.log
  - Windows: %APPDATA%\Claude\logs\mcp*.log
- Ensure Node.js is installed globally
- Verify the configuration file syntax
- Try restarting Claude Desktop

Contributing

Contributions are welcome! Please feel free to submit an issue or a pull request.

Support

For issues and feature requests, please create an issue in the GitHub repository.