Metadata-Version: 2.4
Name: datasignals-events-mcp
Version: 1.0.0
Summary: MCP server for the DataSignals Events API: eleven US filing event streams in one schema, each record linking back to its own filing.
Project-URL: Homepage, https://datasignalslab.com/events-api.html
Project-URL: Documentation, https://datasignalslab.com/events-api-quickstart.html
License-Expression: MIT
License-File: LICENSE
Keywords: 13f,edgar,fda,filings,form-d,insider-trading,mcp,sec
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: mcp<3,>=2.0
Description-Content-Type: text/markdown

# DataSignals Events MCP server

Ask an AI assistant about US regulatory filings and have it answer from the
filings themselves, with a link back to each one.

This is a small MCP server that runs on your own machine and talks to the
[DataSignals Events API](https://datasignalslab.com/events-api.html) with your
key. Eleven streams in one schema: insider buying clusters, planned insider sales
(Form 144), activist stakes (13D/G), institutional holdings (13F), material
corporate events (8-K), private capital raises (Form D), FDA actions, biotech
trial catalysts, NIH grants, federal contract awards and congressional trades.

There is nothing to sign up for beyond the API key you already have, and nothing
is billed twice: a call here spends one thing, the monthly event allowance on
your plan.

## Install

```bash
pip install datasignals-events-mcp
```

## Configure your client

Add this to your MCP client configuration, with your own key. In Claude Desktop
the file is `claude_desktop_config.json`; Cursor, Zed and the others use the same
shape.

```json
{
  "mcpServers": {
    "datasignals-events": {
      "command": "datasignals-events-mcp",
      "env": {
        "DATASIGNALS_KEY": "ds_live_your_key_here"
      }
    }
  }
}
```

Restart the client. Ask it to run `check_setup` and it will tell you whether the
key is configured and whether the feed answers.

No key yet? Two of the tools, `list_event_types` and `feed_health`, work without
one, so you can see the shape of the data and how fresh it is before you decide.
Plans, including a free one, are at
<https://datasignalslab.com/events-api.html>.

## What you can ask

The tools are built around questions rather than endpoints:

| Tool | Answers |
|---|---|
| `search_events` | "Which FDA actions this week scored above 70?" |
| `company_events` | "What has been filed on NVDA lately, across all streams?" |
| `get_event` | "Show me everything on this one event." |
| `list_event_types` | "Which fields does the Form D stream actually carry?" |
| `feed_health` | "How current is this data right now?" |
| `usage` | "How much of my allowance is left, and when does it reset?" |
| `check_setup` | "Is this thing configured correctly?" |

Every record carries the URL of the filing it was parsed from. Where a record has
a score, it also carries the terms that score was built from and a flag saying
whether those terms were complete; when a term is missing from the published
source that flag is `false` rather than a number being invented.

## Honest limits

- **Not real time.** Sources refresh once a night, congressional trades weekly
  and 13F quarterly, because that is how often they are published. The freshest
  an event can be is this morning's round.
- **Published filings only.** The archive holds what was published, not
  everything a source ever had.
- **Not investment advice.** This is data for research and monitoring.

## Environment variables

| Variable | Meaning |
|---|---|
| `DATASIGNALS_KEY` | Your API key, starting with `ds_live_`. Required for everything except `list_event_types` and `feed_health`. |
| `DATASIGNALS_BASE_URL` | Override the API base URL. You will not normally need this. |

The key is sent as an `Authorization` header and never as a query parameter, so
it does not end up in server logs or browser history. Keep it server-side;
anyone holding it can spend your allowance.

## Development

```bash
python3 -m venv .venv
.venv/bin/pip install -e . pytest
.venv/bin/python -m pytest tests -q
```

The tests use a mock transport and never touch the network, except for the
handshake tests, which start the server for real and speak MCP to it over stdio
against a deliberately unreachable endpoint.

## Support

<support@datasignalslab.com>, or the quickstart at
<https://datasignalslab.com/events-api-quickstart.html>.

MIT licensed.
