# CTI MCP Server

[中文](README_zh-CN.md) ｜ [En](README.md)

CTI MCP Server is a lightweight MCP (Message/Tool Call Protocol) service framework that packages and exposes multiple tools for a Threat Intelligence Agent, enabling automated triage, evidence queries, and centralized integration.

**Key Features**

- Lightweight: uses `fastmcp` to wrap tools as remotely callable MCP methods.
- TI-focused: built-in IoC lookups, event backtracking, and basic IP enrichment.
- Model-integrated: works with OpenAI and other LLMs so the model can call MCP tools during analysis to gather evidence.
- Easy to debug and deploy locally with CLI (Typer) support.

**Quick Start**

Prepare Python (project requires Python >= 3.14) and create a virtual environment:

```bash
python -m venv .venv
source .venv/bin/activate
pip install -e .
```

Start the MCP SSE service (defaults to 127.0.0.1:8000, path /mcp):

```bash
uv run cti-mcp-server start
# or
python -m cti_mcp_server.server start
```

Custom host/port/path example:

```bash
cti-mcp-server start --host 0.0.0.0 --port 8000 --path /mcp
```

Enable authentication (recommended for public internet exposure):

```bash
export CTI_MCP_AUTH_TOKEN="replace-with-a-long-random-token"
cti-mcp-server start --host 0.0.0.0 --port 8000 --path /mcp
```

You can also pass it directly:

```bash
cti-mcp-server start --auth-token "replace-with-a-long-random-token"
```

When auth is enabled, clients must send header:

```text
Authorization: Bearer <your-token>
```

Validate locally with the Agent example (connects to local MCP service):

```bash
cti-agent 8.8.8.8
```

Use custom model endpoint / key / model (OpenAI-compatible API):

```bash
cti-agent 8.8.8.8 \
	--mcp-url http://127.0.0.1:8000/mcp \
	--llm-base-url http://127.0.0.1:11434/v1 \
	--llm-api-key ollama \
	--model qwen3:latest
```

`cti-agent` command arguments:

- Positional argument: `ioc` (required), e.g. IP/domain.
- `--mcp-url`: MCP service URL (default `http://127.0.0.1:8000/mcp`).
- `--llm-base-url`: OpenAI-compatible model API base URL.
- `--llm-api-key`: API key for the model endpoint.
- `--model`: model name (for example `qwen3:latest`).

**Built-in MCP Tools (Examples)**

- `ioc_type(ioc: str) -> str`: Detects IoC type (IP / domain).
- `local_summary(ioc: str) -> dict`: Returns structured summary from the local intel store (verdict, tags, first_seen, etc.).
- `local_events(ioc: str, limit: int=20) -> dict`: Returns recent observed events (for evidence lists).
- `ip_basic(ip: str) -> dict`: Offline basic IP enrichment (private/public determination, geo/ASN placeholder info).

**Development & Testing**

- Run tests: `pytest`
- Lint/format: `ruff .`
- Dependency management and packaging via `pyproject.toml`.

**Contributing**

Issues and PRs are welcome. Please describe the problem and purpose of changes in the PR, keep commits tidy, provide test coverage, and include a brief explanation.

**License**

See the `LICENSE` file in the repository (or otherwise negotiated if absent).

---
Thanks for using CTI MCP Server. For help, please open an issue in the repository.