Metadata-Version: 2.4
Name: cyberspf-mcp
Version: 0.2.2
Summary: Ask CyberSPF about a domain, IP or ASN from an MCP client. mcprush.com-17295b68beea8c4ddd3f65a0
Author-email: Trontech Inc <hello@cyberspf.com>
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://cyberspf.com
Project-URL: Documentation, https://cyberspf.com/api/v1/docs/
Keywords: mcp,security,dns,dmarc,spf,bgp,threat-intel
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: System Administrators
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp==1.9.4
Requires-Dist: httpx==0.28.1
Requires-Dist: anyio==4.6.2.post1

<!-- mcp-name: com.cyberspf/mcp -->

# CyberSPF MCP server

Ask CyberSPF about an IP, a domain, or an ASN straight from your MCP client —
Claude Desktop, an editor, or an agent framework. See what your account
monitors and pull your graded report card without leaving the client.

## How it works

The server runs on your own machine and calls CyberSPF over HTTPS with your own
API key. Your requests go straight from your machine to CyberSPF, so there is no
third-party service in between and no extra account to set up. Your MCP client
starts and stops it for you — there is no service to keep running.

## What you need

A CyberSPF plan that includes **API access**. The `cyberspf_report_card` tool
also needs a plan that includes **the report card**. That is a separate part of
your plan, so if your lookups work but the report card is refused, it means your
plan does not cover it — not that your key is wrong.

## Install

Nothing to install — `uvx` fetches and runs it:

```bash
uvx cyberspf-mcp
```

Or into an environment you manage:

```bash
pip install cyberspf-mcp
```

## Configure

Create an API key in CyberSPF under **Settings → Webhooks and API**, then point
your client at the server. For Claude Desktop, add this to
`claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "cyberspf": {
      "command": "uvx",
      "args": ["cyberspf-mcp"],
      "env": {
        "CYBERSPF_API_KEY": "your key here"
      }
    }
  }
}
```

If the server shows up in your client's list but never answers, the usual cause
is that the client cannot find `uvx` — put its full path in `command`.

## On the MCP Registry

Listed on the official MCP Registry as **`com.cyberspf/mcp`**.

## The tools

| Tool | Answers |
|---|---|
| `cyberspf_investigate` | **start here** — looks one thing up and follows what it points at, in a single call |
| `cyberspf_lookup` | one IP, domain, CIDR or ASN — ordered sections of findings with severities |
| `cyberspf_list_monitors` | what this account watches, and when each was last checked |
| `cyberspf_report_card` | the graded assessment per monitored domain, with recommendations |
| `cyberspf_alerts` | what changed, newest first — page with `before`, poll with `since` |
| `cyberspf_threat_lists` | the account's threat lists, their tags and sizes |
| `cyberspf_tag_suggestions` | tags already in use, so a new one is not a near-miss of an old one |
| `cyberspf_bulk_lookup` | submit many terms at once; returns a job id |
| `cyberspf_bulk_result` | collect a bulk job — polling is free |

`cyberspf_investigate` and `cyberspf_lookup` both take `detail`: `summary`
returns only findings rated bad or warn plus a count of every severity seen,
which is far less to read. Investigate defaults to summary because it returns
several subjects at once; lookup defaults to full.

These change your account:

| Tool | Does |
| --- | --- |
| `cyberspf_start_monitoring` | begin watching a domain, IP or ASN |
| `cyberspf_stop_monitoring` | stop watching one |
| `cyberspf_create_threat_list` | create an empty list, named, tagged and graded |
| `cyberspf_add_to_threat_list` | add hosts, IPs or CIDR blocks — up to 100 a call |
| `cyberspf_remove_from_threat_list` | take entries back out |

The tools that change your account say so in their description, and the two that
remove protection — stopping a monitor or un-flagging a threat — ask your
assistant to confirm with you first. A monitor that is quietly switched off
stops telling you when something changes, without saying so.

### Following a result instead of stopping at it

`cyberspf_lookup` returns CyberSPF's own sections unflattened, on purpose. Values
that can themselves be looked up carry a `type` (`ip`, `domain`, `asn`, `cidr`),
so your assistant can feed one straight back in:

> look up `example.com` → take the addresses it resolves to → look each up →
> take the ASN announcing them → look that up

That chaining is why the response stays structured. Flattening it into prose
would read more smoothly but would drop the `type` field the chain depends on.

## Examples

Ask your assistant in plain language — it fills in the arguments from each
tool's schema. The arguments are shown here so you can see the shape.

**Look something up**

> "What do you know about example.com?"
→ `cyberspf_investigate` · `{ "term": "example.com" }` — follows the domain to
its addresses and the ASN announcing them, in one call.

> "Give me the full assessment of 8.8.8.8"
→ `cyberspf_lookup` · `{ "term": "8.8.8.8", "detail": "full" }`

**See what's watched, graded, or changed**

> "What am I monitoring?" → `cyberspf_list_monitors` (no arguments)
> "Show me the report cards" → `cyberspf_report_card` (no arguments)
> "Anything new since yesterday?"
→ `cyberspf_alerts` · `{ "since": "2026-10-17T00:00:00Z" }`

**Start or stop monitoring**

> "Monitor example.com and email me when it changes"
→ `cyberspf_start_monitoring` · `{ "term": "example.com", "alert_methods": ["email"] }`
(methods: `email`, `web_notification`, `log`, `webhook`)

> "Stop monitor 42" → `cyberspf_stop_monitoring` · `{ "monitor_id": 42 }`

**Threat lists**

> "What tags do I already use?"
→ `cyberspf_tag_suggestions` · `{ "q": "phish" }` (`q` optional)

> "What lists do I have?" → `cyberspf_threat_lists` (no arguments)

> "Create a high-severity list called 'Phishing kits', tagged phishing"
→ `cyberspf_create_threat_list` ·
`{ "title": "Phishing kits", "severity": "high", "tags": ["phishing"] }`
(`severity`: `critical` / `high` / `medium` / `low` / `info`, default `medium`;
`title` is the only required field)

> "Add 1.2.3.4, evil.example and 10.0.0.0/24 to list 7"
→ `cyberspf_add_to_threat_list` ·
`{ "list_id": 7, "items": ["1.2.3.4", "evil.example", "10.0.0.0/24"] }`

> "Take evil.example back out of list 7"
→ `cyberspf_remove_from_threat_list` · `{ "list_id": 7, "items": ["evil.example"] }`

**Many at once**

> "Check these fifty domains"
→ `cyberspf_bulk_lookup` · `{ "terms": "a.com\nb.com\nc.com" }` — returns a `job_id`

> "Collect bulk job abc123"
→ `cyberspf_bulk_result` · `{ "job_id": "abc123" }`

## Error messages

Every error tells you what to do about it:

| Condition | What the tool says |
|---|---|
| no `CYBERSPF_API_KEY` | exits at startup, naming the setting — rather than appearing healthy and failing on first use |
| 401 | the key was rejected; check it has not been revoked |
| 403 | the key is valid, the plan does not include what was asked for |
| 429 | daily allowance used up, resets midnight UTC |
| timeout | 45s, and says a first lookup of a cold domain can be slow before concluding it is down |

A blank search term is rejected before it is sent, so it does not use up one of
your daily calls.

## What calling these tools does

The service first serves what CyberSPF has already gathered but a lookup of a domain
CyberSPF hasn't seen before may gather fresh data from public sources.

CyberSPF does reach out to the domains it monitors to collect TLS
handshakes and HTTP headers, from a dedicated prober identifying itself as
`CyberSPF-Prober` — on its own schedule, independent of when you run a tool.
