90 lines
2.2 KiB
Markdown
90 lines
2.2 KiB
Markdown
|
# Installation Guide for Vikunja MCP Server
|
||
|
|
|
||
|
|
This guide provides instructions for setting up and running the Vikunja MCP server locally.
|
||
|
|
|
||
|
|
## Prerequisites
|
||
|
|
|
||
|
|
- Python 3.10 or newer
|
||
|
|
- `pip` (Python's package installer)
|
||
|
|
|
||
|
|
## Setup Instructions
|
||
|
|
|
||
|
|
Follow these steps to get the application running.
|
||
|
|
|
||
|
|
**1. Create a Virtual Environment**
|
||
|
|
|
||
|
|
It is highly recommended to run this application in a Python virtual environment to avoid conflicts with system-wide packages.
|
||
|
|
|
||
|
|
Create the environment using the following command:
|
||
|
|
```bash
|
||
|
|
python3 -m venv .venv
|
||
|
|
```
|
||
|
|
|
||
|
|
**2. Activate the Virtual Environment**
|
||
|
|
|
||
|
|
Before installing dependencies or running the application, you must activate the virtual environment.
|
||
|
|
|
||
|
|
* **On macOS and Linux:**
|
||
|
|
```bash
|
||
|
|
source .venv/bin/activate
|
||
|
|
```
|
||
|
|
|
||
|
|
* **On Windows:**
|
||
|
|
```bash
|
||
|
|
.\.venv\Scripts\activate
|
||
|
|
```
|
||
|
|
|
||
|
|
Your terminal prompt should change to indicate that you are now in the `.venv` environment.
|
||
|
|
|
||
|
|
**3. Install Dependencies**
|
||
|
|
|
||
|
|
With the virtual environment active, install the required Python packages from the `requirements.txt` file.
|
||
|
|
```bash
|
||
|
|
pip install -r requirements.txt
|
||
|
|
```
|
||
|
|
|
||
|
|
## Configuration
|
||
|
|
|
||
|
|
The application requires three environment variables to connect to your Vikunja instance. You must set these in your terminal before running the server.
|
||
|
|
|
||
|
|
Replace the placeholder values with your actual credentials.
|
||
|
|
|
||
|
|
```bash
|
||
|
|
export VIKUNJA_URL="https://your-vikunja-instance.com"
|
||
|
|
export VIKUNJA_USERNAME="your_username"
|
||
|
|
export VIKUNJA_PASSWORD="your_password"
|
||
|
|
```
|
||
|
|
|
||
|
|
**Note:** These variables are only set for the current terminal session. If you open a new terminal, you will need to set them again.
|
||
|
|
|
||
|
|
## Running the Application
|
||
|
|
|
||
|
|
Once the setup and configuration are complete, you can run the application with the following command:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
python main.py
|
||
|
|
```
|
||
|
|
|
||
|
|
This will launch the interactive MCP shell.
|
||
|
|
|
||
|
|
## Usage
|
||
|
|
|
||
|
|
Here are the basic commands to get started:
|
||
|
|
|
||
|
|
1. **Log in** to your Vikunja instance:
|
||
|
|
```
|
||
|
|
> login
|
||
|
|
```
|
||
|
|
|
||
|
|
2. **Search for tasks**:
|
||
|
|
```
|
||
|
|
> search_tasks "My search query"
|
||
|
|
```
|
||
|
|
|
||
|
|
3. **Add a new task** to a project:
|
||
|
|
```
|
||
|
|
> add_task <project_id> "My new task title"
|
||
|
|
```
|
||
|
|
|
||
|
|
You can type `help` at any time to see a full list of commands, or `help <command_name>` for details on a specific one. To close the application, type `exit`.
|