Getting Started with the oCIS MCP Server

Hey there! This guide will help you connect an AI assistant (like Claude or an Ollama model) to your ownCloud files. Don't worry if some of this is new to you -- we'll go step by step.

What does this do?

Imagine you have files stored in the cloud using ownCloud (called oCIS). Now imagine you could talk to an AI and say things like:

"Show me all my files"
"Create a new folder called Homework"
"Share my project with my friend"

That's exactly what this MCP server does. It's like a translator between an AI assistant and your cloud files. The AI talks to the MCP server, and the MCP server talks to oCIS.

You  -->  AI Assistant  -->  MCP Server  -->  Your oCIS Cloud Files

What you need

Before we start, make sure you have:

A computer (Mac, Windows, or Linux)
An oCIS server running somewhere (your school or organization might have one, or you can run one with Docker)
Either Claude Desktop or Ollama installed (we'll cover both below)
Go installed (version 1.25 or newer) -- only needed if building from source. Get it from go.dev/dl. Not needed if you download a pre-built binary.

Step 1: Get the MCP Server Ready

You can either download a pre-built binary (easiest) or build from source.

Option A: Download from Releases (recommended)

Go to the Releases page and download the right file for your system:

System	File to download
Mac (Apple Silicon / M1-M4)	`ocis-mcp-server_*_darwin_arm64.tar.gz`
Mac (Intel)	`ocis-mcp-server_*_darwin_amd64.tar.gz`
Windows	`ocis-mcp-server_*_windows_amd64.zip`
Linux	`ocis-mcp-server_*_linux_amd64.tar.gz`

Extract it somewhere you'll remember (like your home folder).

On Mac/Linux, open a terminal and run:

cd ~/Downloads
tar xzf ocis-mcp-server_*.tar.gz
chmod +x ocis-mcp-server
mv ocis-mcp-server ~/ocis-mcp-server

On Windows, right-click the .zip file and select "Extract All".

Mac users -- important! macOS blocks downloaded programs by default. You need to run this command once to allow it:
xattr -d com.apple.quarantine ~/ocis-mcp-server
If you skip this step you'll see "Apple could not verify this software" or "Permission denied" when Claude Desktop tries to start the server.

Option B: Build from source

If you have Go installed (version 1.25+), you can build it yourself:

git clone https://github.com/owncloud/ocis-mcp-server.git
cd ocis-mcp-server
go build -o ocis-mcp-server ./cmd/ocis-mcp-server

On Windows, the built file will be called ocis-mcp-server.exe.

Tip: Run ./install.sh (Mac/Linux) to automatically check what's installed on your system and help you set everything up. See Using the Install Script below.

Step 2: Get Your oCIS App Token

To let the MCP server talk to oCIS, you need a special password called an app token. There are two ways to get one:

Option A: Using the command line (most common)

If your oCIS runs in Docker, open a terminal and run:

docker compose exec ocis ocis auth-app create \
  --user-name="admin" \
  --expiration="8760h"

This creates a token that lasts for 1 year (8760 hours). It will print something like:

App token created:
  User: admin
  Token: WExn...long-string-here...kQ==

Write down both the user name and the token -- you'll need them in the next step!

Option B: Using the web interface

If your oCIS has ocis-app-tokens installed, you can create tokens through the web browser. Open the app-tokens page, click "Create", give it a name like "MCP Server", and copy the token that appears.

Connect with Claude Desktop

Claude Desktop is an app from Anthropic that lets you chat with Claude AI. It has built-in support for MCP servers, so connecting is easy.

First, find out the full path to your ocis-mcp-server file. For example:

Mac/Linux: /home/yourname/ocis-mcp-server/ocis-mcp-server
Windows: C:\Users\yourname\ocis-mcp-server\ocis-mcp-server.exe

You can find it by running pwd in the terminal while inside the project folder.

On Mac

Open Finder.
Press Cmd + Shift + G and paste this path:
```
~/Library/Application Support/Claude
```
Open (or create) the file claude_desktop_config.json.
Paste this inside (replace the placeholder values with your own):

{
  "mcpServers": {
    "ocis": {
      "command": "/full/path/to/ocis-mcp-server",
      "env": {
        "OCIS_MCP_OCIS_URL": "https://your-ocis-server.example.com",
        "OCIS_MCP_APP_TOKEN_USER": "admin",
        "OCIS_MCP_APP_TOKEN_VALUE": "your-token-here"
      }
    }
  }
}

Save the file and restart Claude Desktop (quit it completely and open it again).

On Windows

Press Win + R, type this, and press Enter:
```
%APPDATA%\Claude
```
Open (or create) the file claude_desktop_config.json.
Paste this inside:

{
  "mcpServers": {
    "ocis": {
      "command": "C:\\Users\\yourname\\ocis-mcp-server\\ocis-mcp-server.exe",
      "env": {
        "OCIS_MCP_OCIS_URL": "https://your-ocis-server.example.com",
        "OCIS_MCP_APP_TOKEN_USER": "admin",
        "OCIS_MCP_APP_TOKEN_VALUE": "your-token-here"
      }
    }
  }
}

Save the file and restart Claude Desktop.

On Linux

Open a terminal and run:

mkdir -p ~/.config/Claude
nano ~/.config/Claude/claude_desktop_config.json

Paste this inside:

{
  "mcpServers": {
    "ocis": {
      "command": "/full/path/to/ocis-mcp-server",
      "env": {
        "OCIS_MCP_OCIS_URL": "https://your-ocis-server.example.com",
        "OCIS_MCP_APP_TOKEN_USER": "admin",
        "OCIS_MCP_APP_TOKEN_VALUE": "your-token-here"
      }
    }
  }
}

Press Ctrl + O to save, then Ctrl + X to exit nano.
Restart Claude Desktop.

Try it out!

Open Claude Desktop and try typing:

"List all my spaces"
"What files are in my personal space?"
"Create a folder called 'My Project' in my personal space"

You should see Claude use the oCIS tools to do what you asked!

Connect with Ollama

Ollama lets you run AI models on your own computer for free. It doesn't directly speak MCP, so we need a small helper tool called mcphost that acts as a bridge.

You  -->  mcphost  -->  Ollama (AI brain)
               |
               +--->  MCP Server  -->  oCIS

Step 1: Install Ollama

On Mac

# Using Homebrew
brew install ollama

# Or download from https://ollama.com/download/mac

On Windows

Download the installer from ollama.com/download/windows and run it.

On Linux

curl -fsSL https://ollama.com/install.sh | sh

Step 2: Download an AI model

Open a terminal and run:

ollama pull llama3.2

This downloads a free AI model to your computer. It might take a few minutes depending on your internet speed.

Step 3: Install mcphost

mcphost is the bridge between Ollama and MCP servers. Install it with:

go install github.com/mark3labs/mcphost@latest

Make sure $(go env GOPATH)/bin is in your PATH. If you're not sure, run:

# Mac / Linux
export PATH="$PATH:$(go env GOPATH)/bin"

# On Windows (PowerShell)
$env:PATH += ";$(go env GOPATH)\bin"

Step 4: Create the mcphost config

Important: mcphost looks for its config file directly in your home directory -- ~/.mcphost.yml or ~/.mcphost.json -- not inside a .mcphost folder. It also uses the key environment (not env) for environment variables. Using the wrong path or key will make mcphost start with zero tools loaded, with no error message telling you why.

On Mac / Linux

Create the file ~/.mcphost.json:

{
  "mcpServers": {
    "ocis": {
      "type": "local",
      "command": ["/full/path/to/ocis-mcp-server"],
      "environment": {
        "OCIS_MCP_OCIS_URL": "https://your-ocis-server.example.com",
        "OCIS_MCP_APP_TOKEN_USER": "admin",
        "OCIS_MCP_APP_TOKEN_VALUE": "your-token-here"
      }
    }
  }
}

On Windows

Create the file at %USERPROFILE%\.mcphost.json:

notepad "$env:USERPROFILE\.mcphost.json"

Paste the same JSON content as above (use the Windows path to your ocis-mcp-server.exe).

Step 5: Run it!

mcphost --model ollama:llama3.2

You'll get a chat prompt. Try typing:

"Check if the oCIS server is healthy"
"List all users"
"What spaces do I have?"

Note: Ollama models run locally on your computer. They need a decent amount of RAM (at least 8 GB free). If things are slow, try a smaller model: ollama pull llama3.2:1b and use mcphost --model ollama:llama3.2:1b.

Using the Install Script

We've included a helper script that checks your system and helps set things up. Run it from the project folder:

# Mac / Linux
chmod +x install.sh
./install.sh

The script will:

Detect your operating system
Check if Go, Docker, Claude Desktop, Ollama, and mcphost are installed
Show you a status report of what's ready and what's missing
Offer to build the MCP server for you
Offer to write the config files for Claude Desktop and/or mcphost

It will always ask before changing anything on your computer.

Windows users: Run the script inside WSL (Windows Subsystem for Linux) or Git Bash.

Troubleshooting

"Permission denied" or "Apple could not verify" (Mac only)

macOS blocks programs downloaded from the internet. Run this in Terminal:

xattr -d com.apple.quarantine /path/to/ocis-mcp-server

Replace /path/to/ocis-mcp-server with the actual location of the file.

"Connection refused" or "cannot connect"

Double-check your oCIS URL. Can you open it in a web browser?
Make sure the oCIS server is running.
If using https://localhost, you may need to add OCIS_MCP_INSECURE=true to your config.

"Authentication failed" or "401 error"

Check that your app token user and value are correct.
Make sure there are no extra spaces when you copy-paste the token.
The token might have expired -- create a new one.

mcphost says "Loaded 0 tools from MCP servers"

This means mcphost never found your config, and it fails silently -- no error, no warning.

Check the file is at ~/.mcphost.yml or ~/.mcphost.json (a file directly in your home folder), not inside a .mcphost/ folder.
Check you used "environment" as the key for environment variables, not "env". mcphost still accepts "env" in some code paths, but silently drops it in others -- "environment" is the one that reliably works.
If mcphost ever auto-created an empty ~/.mcphost.yml for you (it does this the first time it can't find any config), make sure your real server config ends up in that same file -- a leftover empty one will take priority over a ~/.mcp.json you edit later.

"Command not found"

Make sure the path to ocis-mcp-server in your config file is correct.
Try using the full absolute path (starting with / on Mac/Linux or C:\ on Windows).
If you used go build, the binary is in the project folder.

Claude Desktop doesn't show oCIS tools

Make sure you saved the config file in the right location for your OS (see above).
Make sure the JSON is valid (no missing commas, brackets, etc.).
Restart Claude Desktop completely (quit and reopen).

Ollama is slow

Try a smaller model: ollama pull llama3.2:1b
Close other apps to free up memory.
Ollama works best with at least 8 GB of free RAM.

Cool Things to Try

Here are some fun prompts to get you started:

"Show me what's in my personal space" -- See all your files and folders.
"Create a folder called 'School Projects' and then create three subfolders inside it: Math, Science, and History" -- Watch the AI create a whole folder structure for you!
"Search for all PDF files" -- Find every PDF across all your spaces.
"Share my 'School Projects' folder with marie@example.com as a viewer" -- Collaborate with friends.
"Give me an overview of all my spaces -- how much storage am I using?" -- Get a summary of everything.
"Find all files tagged 'important' and tell me when they were last modified" -- Use tags to organize your stuff.

Next Steps

Check out the full README for all 80 tools and advanced configuration.
Look at the MCP Prompts for guided workflows like onboarding users and generating sharing reports.
Want to help improve this project? See the Contributing section.

Happy coding!

FilesExpand file tree

GETTING_STARTED.md

Latest commit

History

GETTING_STARTED.md

File metadata and controls

Getting Started with the oCIS MCP Server

What does this do?

What you need

Step 1: Get the MCP Server Ready

Option A: Download from Releases (recommended)

Option B: Build from source

Step 2: Get Your oCIS App Token

Option A: Using the command line (most common)

Option B: Using the web interface

Connect with Claude Desktop

On Mac

On Windows

On Linux

Try it out!

Connect with Ollama

Step 1: Install Ollama

On Mac

On Windows

On Linux

Step 2: Download an AI model

Step 3: Install mcphost

Step 4: Create the mcphost config

On Mac / Linux

On Windows

Step 5: Run it!

Using the Install Script

Troubleshooting

"Permission denied" or "Apple could not verify" (Mac only)

"Connection refused" or "cannot connect"

"Authentication failed" or "401 error"

mcphost says "Loaded 0 tools from MCP servers"

"Command not found"

Claude Desktop doesn't show oCIS tools

Ollama is slow

Cool Things to Try

Next Steps