Segnals MCP Server

Manage your Segnals trading bots, strategies, PnL, and the strategy marketplace from any AI agent (Claude, Cursor, Claude Code, Windsurf, Copilot, etc.) — securely, by just talking.

Built by Segnals · Secure Algorithmic Trading Ecosystem

Table of Contents

• See It in Action

• What Is This? / What Is Segnals?

• Features & Capability Overview

• Quickstart (60 Seconds)

• Getting Your API Key (Onboarding)

• Installation

• Client Configuration

• Authentication & Scopes

• Tool Reference

• Security Model

• Safety & Disclaimer

• Example Use-Cases & Prompt Library

• Architecture

• Compatibility Matrix

• Troubleshooting

• For AI Agents

• Roadmap

• Contributing & Support

• License

Related MCP server: vibetrader-mcp

See It in Action

Here is how a conversation with an MCP-enabled agent flows:

Use Case 1: Checking Portfolio Performance

User: How did my bots perform in October?

Agent: (Calls segnals_get_pnl_summary({ start_date: "2026-10-01", end_date: "2026-11-01" }))

Agent: You have 3 active bots out of 5. From 1 October to 1 November:

• Total PnL: +$245.50

• Win Rate: 68%

• Trades: 25

Use Case 2: Strategy Creation with Two-Step Confirmation Gate

User: Set up a new Conservative EURUSD Forex bot with 2:1 Reward ratio.

Agent: (Calls segnals_create_strategy with confirm: false)

Agent: ✋ Preview Strategy Configuration:

• Name: Conservative EURUSD Trend

• Symbol: EURUSD

• Asset Class: Forex (MetaTrader 5)

• Leverage: 1:30

• Risk Parameters: Stop Loss = 20 pips, Take Profit = 40 pips (2:1 Ratio)

• Estimated Drawdown Warning: 1.5%

To proceed and save this bot to your dashboard, please reply with "confirm".

User: Confirm

Agent: (Calls segnals_create_strategy with confirm: true)

Agent: ✅ Strategy has been created successfully. You can find it on your dashboard or manage it here by asking me to list your bots.

What Is This? / What Is Segnals?

Segnals is an institutional-grade, multi-tenant algorithmic trading and AI ecosystem. It enables retail traders and quants to write, backtest, and deploy high-frequency trading (HFT) bots across cryptocurrency exchanges (via CCXT) and Forex brokers (via a custom MetaTrader 5 Redis bridge).

The Segnals MCP Server is a thin, secure gateway designed for the Model Context Protocol (MCP). It exposes a set of strictly typed developer APIs as tools to large language models (LLMs). This allows AI agents to read trading statistics, create strategies, modify parameters, and manage marketplace listings on behalf of the user, using secure, cryptographically hashed user keys.

🔒 Security Boundaries (Can / Can't Do)

• WHAT IT CAN DO:

  • Fetch account balance, statistics, and historical PnL logs.

  • List, query, and monitor active trading bot statuses.

  • Create, modify, start, stop, restart, or delete trading bots.

  • Browse the Strategy Marketplace and copy/purchase strategies.

  • Modify notification preferences and read the market newsfeed.

• WHAT IT CANNOT DO (Strict Hard Exclusions):

  • ❌ No Fund Movement: Cannot deposit, withdraw, or transfer funds.

  • ❌ No Secret Retrieval: Cannot read, export, or enter API secrets for Bybit/MetaTrader 5. All exchange secrets are configured exclusively in the web dashboard.

  • ❌ No Administrative Overrides: Cannot modify user profile settings, credentials, passwords, or emails.

Features & Capability Overview

The server exposes 33 distinct tools structured across the following trading features:

• Account & Meta: Verify the key and read the account tier, subscription, and which exchanges are connected.

• Stats: Read the dashboard and profit/loss for a period (24h, 7d, 30d, all, or a date range), per-bot performance, and trades.

• Life Cycle Control: Create, update, start, stop, restart, and delete bots.

• Indicator Filter: Switch the ADX, RSI, EMA, and ATR gates of a bot's indicator filter on or off and set their parameters.

• Copy Trading & Marketplace: Browse listings, copy paid or free strategies, and manage public offerings.

• Market Feed: Read the market newsfeed.

For inputs, outputs, and JSON examples for each tool, see the Tool Reference Guide.

Quickstart (60 Seconds)

1. Get an API Key

Log in to your dashboard at segnals.com, navigate to Settings → API Keys, generate a key, and select the desired scopes (e.g., read:account, read:bots). Copy the token (sk_live_... or sk_test_...).

2. Configure Claude Desktop

Open your Claude Desktop configuration file (see location directories below) and add the server. This runs the published Docker image, so Docker must be installed (to run from source instead, see Installation):

{
  "mcpServers": {
    "segnals-mcp": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-e", "SEGNALS_API_KEY", "ghcr.io/eidostein/segnals-mcp:latest"],
      "env": {
        "SEGNALS_API_KEY": "sk_live_your_actual_key_here"
      }
    }
  }
}

3. Verify Connection

Restart Claude Desktop and ask the agent:

"Use segnals_whoami to verify who I am connected as on Segnals."

Getting Your API Key (Onboarding)

To integrate your agent with your account, you must mint a Developer API Key:

1. Navigate to Settings → API Keys on your dashboard.

2. Click Generate Key and assign a descriptive label.

3. Select Scopes: It is recommended to choose only read-only scopes (read:account, read:stats, read:bots) for your first setup. Add write permissions as needed.

4. Specify an optional IP allowlist or expiration date if desired.

5. Click Generate.

6. Copy Token: Copy the displayed token (sk_live_...) immediately. It will only be shown once.

For more details, see the Onboarding Guide.

Installation

There are two ways to run the Segnals MCP server. The package is not published to npm, so there is no npm install for it.

Method A: Docker image (GHCR)

The public image is ghcr.io/eidostein/segnals-mcp. -i keeps stdin open, which the MCP stdio transport needs; -e SEGNALS_API_KEY passes the key from your environment into the container:

export SEGNALS_API_KEY=sk_live_your_key_here
docker run --rm -i -e SEGNALS_API_KEY ghcr.io/eidostein/segnals-mcp:latest

The image is rebuilt on each release tag, so latest is the last release. To run what is on main today, build from source.

Method B: Build from source

Requires Node.js >= 18.

git clone https://github.com/eidostein/segnals-mcp.git
cd segnals-mcp
npm ci
npm run build
export SEGNALS_API_KEY=sk_live_your_key_here
node dist/index.js

Client Configuration

The server runs on standard input/output (stdio) streams. Depending on your editor or chat interface, add the following configuration:

1. Claude Desktop

File locations:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add this entry to your mcpServers object:

{
  "mcpServers": {
    "segnals-mcp": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-e", "SEGNALS_API_KEY", "ghcr.io/eidostein/segnals-mcp:latest"],
      "env": {
        "SEGNALS_API_KEY": "${env:SEGNALS_API_KEY}"
      }
    }
  }
}

(Note: Replace ${env:SEGNALS_API_KEY} with your actual key or define it in your shell profile).

If you built from source, use "command": "node" and "args": ["/absolute/path/to/segnals-mcp/dist/index.js"] instead.

2. Cursor

Navigate to Settings → Features → MCP:

1. Click + Add New MCP Server.

2. Name: segnals

3. Type: command

4. Command: docker run --rm -i -e SEGNALS_API_KEY ghcr.io/eidostein/segnals-mcp:latest (or node /absolute/path/to/segnals-mcp/dist/index.js for a build from source)

5. Environment Variables: Key = SEGNALS_API_KEY, Value = sk_live_...

3. Claude Code (CLI)

Connect directly from the command line, with SEGNALS_API_KEY exported in the same shell:

claude mcp add segnals-mcp -- docker run --rm -i -e SEGNALS_API_KEY ghcr.io/eidostein/segnals-mcp:latest

For a build from source:

claude mcp add segnals-mcp -- node /absolute/path/to/segnals-mcp/dist/index.js

For more details, see the Configuration Guide.

Authentication & Scopes

The server utilizes scoped access tokens to restrict API permissions. The following scopes can be bound to your API key:

The read:knowledge scope has no tool yet: it can be ticked on a key, but nothing in this server needs it. Sentiment, live prices and help search are not offered until the API has routes for them.

For detailed information, see the Authentication Documentation.

Tool Reference

The following table summarizes the 33 tools exposed by the Segnals MCP server:

For complete usage specifications, see docs/TOOLS.md.

Security Model

The Segnals MCP integration enforces safety guidelines:

1. Hashed Key Storage: API keys are hashed with SHA-256 at rest. Plaintext keys are never stored in the database.

2. Explicit Scope Restrictions: Keys are restricted to their defined scopes. If a key is leaked, it can be revoked or rotated instantly without affecting main account passwords.

3. Two-Step Confirmation Gating: Destructive or financially significant tools (e.g., create_bot, start_bot, copy_strategy) require a confirm: true parameter. Calling them without confirm: true returns a safe JSON preview.

4. Exchange Credentials Isolation: Exchange API secrets and MT5 passwords never leave the primary Segnals servers. AI agents can configure where a bot executes, but can never see or export credentials.

5. Per-Key Rate Limiting: The backend limits keys to a default of 120 requests/minute to prevent loop bugs from overloading the API.

6. Immutable Exclusions: Admin functions, billing details, and withdrawal routes are hard-excluded from the API Key pathway.

For further information, see the Safety & Limitations Guide.

Safety & Disclaimer

Example Use-Cases & Prompt Library

You can copy and paste the following prompts to guide your agent:

Strategy Design & Deployment

"Check my active connection status. If connected, list all strategy schemas and help me design a low-risk Grid bot for BTCUSDT on Bybit." Requires: read:bots, write:bots

Performance Review

"Retrieve a summary of my bot performances. Identify which bot has the highest drawdown this week, pull its execution logs, and suggest parameter updates." Requires: read:stats, read:bots

Marketplace Discovery

"Browse the Strategy Marketplace for low-risk, high-rating Forex strategies. Explain the parameters of the top-performing item and copy it to my workspace." Requires: read:marketplace, write:marketplace

Architecture

The Segnals MCP Server acts as an intermediate translator between your local agent and the remote Segnals platform:

┌─────────────────────────────────┐
│        AI Agent / IDE           │ (Claude Desktop, Cursor, etc.)
└────────────────┬────────────────┘
                 │
                 │ stdio (std_in / std_out)
                 ▼
┌─────────────────────────────────┐
│    Segnals MCP Server (Local)   │
└────────────────┬────────────────┘
                 │
                 │ HTTPS (REST API) + Bearer API Key
                 ▼
┌─────────────────────────────────┐
│     Segnals REST API (Remote)   │ (Enforces Rate-Limits, Scopes, and Auditing)
└─────────────────────────────────┘

Compatibility Matrix

Troubleshooting

1. The Server Does Not Appear in Claude Desktop

• Cause: Invalid path configuration or Node.js missing from system path.

• Fix: Check that the configured command starts the server from a terminal: docker run --rm -i -e SEGNALS_API_KEY ghcr.io/eidostein/segnals-mcp:latest needs Docker running, and a build from source needs Node.js (node -v) and an absolute path to dist/index.js. Check the Claude Desktop log files at %APPDATA%\Claude\logs\mcp.log or ~/Library/Logs/Claude/mcp.log.

2. Error Code: 401 Unauthorized

• Cause: Malformed, expired, or incorrect API key format.

• Fix: Ensure your environment key is correctly configured as export SEGNALS_API_KEY=sk_live_... and that the prefix is correct. Make sure the key has not been revoked on the dashboard.

3. Error Code: 403 Forbidden

• Cause: Either the API key lacks the scope the tool needs (the message names the scope), or the API refused the action for its own reason, such as a tier limit or a protected bot (the message starts with "Segnals refused this request" and gives the reason).

• Fix: For a missing scope, verify the scope required by the tool (see Tool Reference) and generate a new key on the dashboard with the appropriate scope. For any other refusal, act on the reason given: adding scopes does not change it.

4. Error Code: 429 Too Many Requests

• Cause: Request rate limit exceeded.

• Fix: Reduce the frequency of commands. AI loops can occasionally flood the API. Check that your client logic is not stuck in an execution loop.

For more details, see the Troubleshooting Guide.

For AI Agents

🤖 If you are an AI Agent: Read AGENTS.md and llms.txt first. These files contain specific context on tool naming rules, safety disclaimers, the mandatory confirmation workflow, and advice on choosing the correct API endpoint.

Roadmap

• Phase 4b: Remote OAuth Integration: Connect your account via OAuth 2.1 protocol for zero-install clients. (Planned)

• Advanced Backtesting: Run backtest jobs directly from the command line. (Planned)

• Dynamic Telemetry WebSocket Stream: Fetch sub-millisecond price changes. (Planned)

Contributing & Support

We welcome contributions to the Segnals MCP server:

• Report bugs and request features in GitHub Issues.

• Read CONTRIBUTING.md and CODE_OF_CONDUCT.md.

• For security reports, please refer to SECURITY.md to report vulnerabilities privately.

• Contact support at support@segnals.com.

License

This project is licensed under the MIT License - see the LICENSE file for details.