Metadata-Version: 2.4
Name: tickwire-mcp
Version: 0.1.0
Summary: Tickwire MCP server: the safe execution layer for AI trading agents on MT4/MT5 (scoped agent keys, kill switches, pre-trade hooks, idempotent orders, truthful outcomes).
Author-email: Tickwire <hello@tickwire.io>
License-Expression: MIT
Project-URL: Homepage, https://tickwire.io/
Project-URL: Documentation, https://tickwire.io/ai-agents/
Project-URL: Changelog, https://tickwire.io/docs/changelog/
Keywords: mcp,model-context-protocol,metatrader,mt4,mt5,trading,ai-agents
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp==2.2.0
Requires-Dist: httpx<1,>=0.27
Requires-Dist: pydantic<3,>=2.6
Requires-Dist: uvicorn<1,>=0.27
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Provides-Extra: examples
Requires-Dist: fastapi>=0.110; extra == "examples"
Dynamic: license-file

# tickwire-mcp

The Tickwire MCP server: MT4/MT5 trading tools for AI agents (Claude, Cursor,
ChatGPT through the API, the OpenAI Agents SDK, or your own), with the safety
built in. An agent uses its own **agent key** (`twag_…`), scoped to accounts
and optionally read-only. Every order goes through the owner's kill switches
and pre-trade hook, is idempotent, is audited with a required reason, and
comes back with a truthful outcome (`applied`, `no_change`, `rejected`,
`held` or `unknown`).

It is a thin client of the Tickwire agent API and never talks to terminals
directly. Full guide: [tickwire.io/ai-agents](https://tickwire.io/ai-agents/).

## Install

**Not published yet.** The commands below won't find the package. Install from source, from the
repository root:

```
pip install ./mcp                  # puts `tickwire-mcp` on PATH
```

> **State on 30 Oct 2026:** still not published. To publish `tickwire-mcp`,
> `ops/local/release.sh` needs a PyPI token (Keychain item
> `tickwire-pypi-token`, or `~/.pypirc`). It is not on the Mac yet. The npm
> token for the TypeScript packages (`tickwire-npm-token`) is missing too. So
> the release cannot run until the owner adds them.

Once it is published:

```
uvx tickwire-mcp --help            # run without installing
pipx run tickwire-mcp --help
pip install tickwire-mcp           # puts `tickwire-mcp` on PATH
```

Python 3.11 or newer. MIT licensed.

## Quick start: Claude Code

1. The account owner creates an agent key (shown once) in the dashboard, or
   with the Python SDK and their API key:
   `Tickwire("https://api.tickwire.io", "YOUR_API_KEY").create_agent_key("my-claude", [account_id])`
   (`POST /v1/agent-keys`). Start with `read_only=True` if the agent should
   only look.
2. Add the server:

```bash
claude mcp add tickwire \
  --env TICKWIRE_AGENT_KEY=twag_... \
  --env TICKWIRE_API_URL=https://api.tickwire.io \
  -- uvx tickwire-mcp stdio
```

3. Ask: *"List my Tickwire accounts, check the health of the first one, then
   buy 0.01 lots of EURUSD. Reason: quickstart test."*

Sandbox and live accounts use the same API URL; the key decides which
accounts the agent sees. `--sandbox` (or `TICKWIRE_SANDBOX=1`) switches to
`TICKWIRE_SANDBOX_URL` instead.

**Claude Desktop / Cursor** (`claude_desktop_config.json`, `.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "tickwire": {
      "command": "uvx",
      "args": ["tickwire-mcp", "stdio"],
      "env": {
        "TICKWIRE_AGENT_KEY": "twag_...",
        "TICKWIRE_API_URL": "https://api.tickwire.io"
      }
    }
  }
}
```

## Configuration

| Variable | Meaning |
|---|---|
| `TICKWIRE_AGENT_KEY` | stdio: the agent key (`twag_…`). Hosted mode reads it per request from `Authorization: Bearer twag_…` |
| `TICKWIRE_API_URL` | the Tickwire API base URL |
| `TICKWIRE_SANDBOX=1` or `--sandbox` | use the sandbox instead |
| `TICKWIRE_SANDBOX_URL` | the sandbox API base URL; required with `--sandbox`. No sandbox host is built in, and it never falls back to live |
| `TICKWIRE_MCP_IDEMPOTENCY_WINDOW_S` | window for derived idempotency keys (default 60) |
| `TICKWIRE_MCP_ALLOWED_HOSTS` | hosted mode: accepted `Host` values (DNS-rebinding protection) |
| `TICKWIRE_MCP_MAX_BODY_BYTES` | hosted mode: largest `/mcp` request body (default 262144, 256 KB); larger gets 413 `payload_too_large` |
| `TICKWIRE_MCP_KEY_CHECK_TIMEOUT_S` | hosted mode: timeout of the agent-key check before `tools/call` (default 1) |
| `TICKWIRE_MCP_KEY_CHECK_TTL_S` | hosted mode: how long a valid key's check is cached (default 60) |

Hosted mode: `initialize` and `tools/list` need only a well-formed `twag_…`
key, on purpose, so MCP directories can list the tools with a placeholder.
`tools/call` checks the key first (`GET /v1/agent/key-check`) and answers 401
`invalid_agent_key` for a dead key, before any tool runs.

## Modes

- `tickwire-mcp stdio` (default): one agent, local.
- `tickwire-mcp http --host 0.0.0.0 --port 8765`: streamable HTTP at `/mcp`
  for many agents; each sends its own key. Put TLS in front.

## Tools

`list_accounts`, `get_agent_permissions`, `get_portfolio`, `get_all_positions`, `get_account_health`,
`get_account_info`, `get_account_snapshot`, `get_positions`, `get_orders`, `get_quote`, `get_quotes`,
`search_symbols`, `get_symbol_spec`, `get_candles`, `get_history`, `get_history_stats`,
`place_order`, `modify_position`, `close_position`, `modify_order`, `cancel_order`, `get_trade_status`,
`get_audit_log`, and the read-only `search_tickwire_docs` (searches the public
docs at `TICKWIRE_DOCS_URL`/llms-full.txt; no account access). Every trading tool requires `reason` and accepts
`client_request_id` (the idempotency key); without one, a repeat within a
minute is recognised and not sent twice. Text from brokers, terminals and
hooks comes back wrapped as `{"untrusted_text": …}` so the model does not
follow instructions found in it.

Demo accounts only while you evaluate.
