# Llamacpp Mcp

> An MCP (Model Context Protocol) wrapper for running local LLMs using llama-cpp-python

- **Type:** MCP server
- **Install:** `agentstack add mcp-lukasmki-llamacpp-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [lukasmki](https://agentstack.voostack.com/s/lukasmki)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [lukasmki](https://github.com/lukasmki)
- **Source:** https://github.com/lukasmki/llamacpp-mcp

## Install

```sh
agentstack add mcp-lukasmki-llamacpp-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# llamacpp-mcp

An MCP (Model Context Protocol) wrapper for running local LLMs using `llama-cpp-python`. This project provides a framework for integrating local language models as MCP tools with built-in support for specialized models like SmileyLlama.

### SmileyLlama Integration
Generate SMILES strings (chemical notation) for drug-like molecules with fine-grained constraints:
- Lipinski's Rule of Five validation
- Hydrogen bond donor/acceptor limits
- Molecular weight and LogP constraints
- Warhead SMARTS pattern matching
- Macrocycle detection and filtering
- And more...

## Installation

### Prerequisites

- Python ≥ 3.13
- `uv` (recommended) or pip

### Setup

Clone the repository and install dependencies:

```sh
git clone 
cd llamacpp-mcp
uv sync
```

### Backend Configuration

The `llama-cpp-python` library requires compilation with hardware acceleration support. Choose the appropriate backend for your system:

**CUDA** (NVIDIA GPUs):
```sh
CMAKE_ARGS="-DGGML_CUDA=on" uv pip install llama-cpp-python --force-reinstall --no-cache-dir
```

**ROCm** (AMD GPUs):
```sh
CMAKE_ARGS="-DGGML_HIPBLAS=on" uv pip install llama-cpp-python --force-reinstall --no-cache-dir
```

**Metal** (Apple Silicon):
```sh
CMAKE_ARGS="-DGGML_METAL=on" uv pip install llama-cpp-python --force-reinstall --no-cache-dir
```

**CPU-only** (no GPU acceleration):
```sh
uv sync
```

## Usage

### Run the agent example

Setup your `example/fastagent.secrets.yaml`:

```yaml
anthropic:
  api_key: your-api-key-here
```

Then run the agent interface in the terminal:

```sh
cd example/
uv run --extra agent agent.py
```

### Running the MCP Server

Start the MCP server with a GGUF model:

```sh
uv run llamacpp-mcp -i /path/to/model.gguf
```

Additional parameters can be passed as command-line arguments:

```sh
uv run llamacpp-mcp --input model.gguf -n_gpu_layers -1 -n_threads 8
```

**Common parameters:**
- `-n_gpu_layers`: Number of model layers to offload to GPU (-1 for all)
- `-n_threads`: Number of CPU threads to use
- `-n_ctx`: Context window size
- `-verbose`: Verbosity level

### Available Tools

#### generate_smiles

Generate SMILES strings for drug-like molecules with optional constraints.

**Parameters:**
- `max_hbond_donors`: Maximum hydrogen bond donors
- `max_hbond_acceptors`: Maximum hydrogen bond acceptors
- `max_molecular_weight`: Maximum molecular weight
- `max_clogp`: Maximum calculated LogP
- `lipinski_rule_of_five`: Enforce Lipinski's Rule of Five
- `rule_of_three`: Enforce Rule-of-Three for fragment-like molecules
- And additional constraint options...

## Dependencies

**Core:**
- `fastmcp>=2.13.1` - MCP server framework
- `llama-cpp-python>=0.3.16` - LLM inference engine

**Optional:**
- `fast-agent-mcp>=0.2.25` - For agent-based integrations

## Development

### Project Setup

The project uses `uv` for dependency management. After installing uv, run:

```sh
uv sync
```

This installs all dependencies in a local virtual environment.

### Adding New Models

To add a new model type:

1. Create a subdirectory under `src/llamacpp_mcp/models/`
2. Implement `models.py` with Pydantic constraint definitions
3. Implement `tools.py` with tool registration function
4. Import and register tools in the main `__init__.py`

## Configuration

Model parameters can be configured via:

1. **Command-line arguments** - Pass directly to `llamacpp-mcp`
2. **Environment variables** - Set before running the server
3. **Agent Tool Configuration** - See `example/fastagent.config.yaml` for reference

## License

MIT License

## Author

Lukas Kim

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [lukasmki](https://github.com/lukasmki)
- **Source:** [lukasmki/llamacpp-mcp](https://github.com/lukasmki/llamacpp-mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-lukasmki-llamacpp-mcp
- Seller: https://agentstack.voostack.com/s/lukasmki
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.