@Chartobserver/ Server

An MCP (Model Context Protocol) server that lets an AI agent — Claude Desktop, etc. — read your portfolio, place paper trades, and check the leaderboard on your ChartObserver account.

ChartObserver is paper trading. This server cannot move real money. It can affect your public leaderboard standing and your visible portfolio.

Source code: https://github.com/bbusche/chartobserver-mcp — see SECURITY.md for the full egress/data-flow disclosure.

What this server sends and where

• Outbound HTTPS to exactly one host: the configured CHARTOBSERVER_API_BASE (default: the ChartObserver production API on AWS API Gateway, https://g2uyqqluc4.execute-api.us-east-2.amazonaws.com/dev).
• It transmits your UID, username, your webhook credential (sent as an X-Webhook-Id identity header on every request for usage metering, and as auth on trade execution), and the trade parameters the agent supplies. Nothing else.
• It reads no files, contacts no other host, collects no telemetry, runs no code fetched at runtime, and has no install scripts.

Install

You don't install this package directly. You add it to your MCP client's configuration and it runs on demand via npx. Pick the section for your client below.

Always pin to @latest. The package spec @chartobserver/mcp-server@latest tells npx to use the newest published version on each launch, so you automatically get fixes and new features. Plain @chartobserver/mcp-server (no tag) can keep running a stale cached copy.

Claude Desktop

Open your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add a chartobserver entry under mcpServers, then restart Claude Desktop:

{
  "mcpServers": {
    "chartobserver": {
      "command": "npx",
      "args": ["-y", "@chartobserver/mcp-server@latest"],
      "env": {
        "CHARTOBSERVER_WEBHOOK_ID": "your-webhook-id-here",
        "CHARTOBSERVER_UID": "your-uid-here",
        "CHARTOBSERVER_USERNAME": "your-username-here"
      }
    }
  }
}

Claude Code

Register the server with one command (run it in your terminal):

claude mcp add chartobserver \
  --env CHARTOBSERVER_WEBHOOK_ID=your-webhook-id-here \
  --env CHARTOBSERVER_UID=your-uid-here \
  --env CHARTOBSERVER_USERNAME=your-username-here \
  --transport stdio \
  -- npx -y @chartobserver/mcp-server@latest

Add --scope user to make it available across all your projects (the default is the current project only). Verify with claude mcp list; remove with claude mcp remove chartobserver.

Other MCP clients (Cursor, Cline, Windsurf, etc.)

Any client that supports stdio MCP servers uses the same shape — a server entry with a command, args, and env. Add this to that client's MCP/server configuration (consult its docs for the file location), then restart it:

{
  "mcpServers": {
    "chartobserver": {
      "command": "npx",
      "args": ["-y", "@chartobserver/mcp-server@latest"],
      "env": {
        "CHARTOBSERVER_WEBHOOK_ID": "your-webhook-id-here",
        "CHARTOBSERVER_UID": "your-uid-here",
        "CHARTOBSERVER_USERNAME": "your-username-here"
      }
    }
  }
}

All three paths run the identical server; the only difference is where each client keeps its configuration. The three environment variables are required in every case (see below).

Where to find your credentials

Sign in at https://chart.observer and open Integrations → AI Agent (MCP) — or go directly to https://chart.observer/integrations/mcp. The page shows your webhook ID, UID, and username with copy buttons and a pre-filled config snippet you can paste straight into your MCP client.

Environment variables

Variable	Required	Default	Description
CHARTOBSERVER_WEBHOOK_ID	yes	—	Your per-user webhook secret. Same value TradingView uses to fire trades into your account. Treat like a password.
CHARTOBSERVER_UID	yes	—	Your numeric user ID.
CHARTOBSERVER_USERNAME	yes	—	Your public username.
CHARTOBSERVER_API_BASE	no	https://g2uyqqluc4.execute-api.us-east-2.amazonaws.com/dev	API Gateway base URL. Override to point at staging during testing. Must be https:.
CHARTOBSERVER_TIMEOUT_MS	no	15000	Per-request timeout in milliseconds (max 120000).

Available tools

Account

Tool	What it does
get_profile	Read your public profile and current USD balance.
get_subscription	Your subscription tier (Basic / Swing Trader / Day Trader / Influencer), monthly usage vs. limits (trades, API calls, AI-assistant messages), renewal date, and recent payments.

Trading

Tool	What it does
place_trade	Place a buy or sell. Defaults to dry_run: true — returns the projected impact without executing. Set dry_run: false only after confirming with the user. token accepts a symbol (SOL), pair (SOLUSD), or name (Solana).
get_balance	Current USD balance (0 for a funded-but-empty account).
get_open_positions	Open positions, grouped by token pair with average cost basis.
get_closed_trades	Recent closed trades (completed buy→sell roundtrips).
get_recent_transactions	Recent raw transactions (open + closed).

Market

Tool	What it does
get_leaderboard	7-day rolling leaderboard: top traders by average % profit.
get_my_ranking	Your position on the leaderboard (or null if not ranked).
get_price	Current price for a token. Accepts a symbol (SOL), pair (SOLUSD / SOL-USD), or name (Solana); quote defaults to USD.
list_supported_tokens	Every supported token-pair, so you can use a valid identifier before pricing or trading.

Portfolio

Tool	What it does
get_portfolio_summary	One-shot snapshot: balance + open positions + recent closed trades + your leaderboard rank. Designed for periodic polling — compare snapshots to detect changes.

Documentation

Tool	What it does
search_docs	Search the ChartObserver documentation and return the most relevant passages, each with its source URL. Use for "how does X work" / setup / integrations / subscriptions / troubleshooting questions; cite the URLs. Not for live account data.

Safety model

• Paper trading only. Trades affect your simulated portfolio and your leaderboard standing. They do not move real money.
• place_trade defaults to dry-run. The AI agent must explicitly pass dry_run: false to execute. You should be asked for confirmation before that happens.
• Live trades are validated. Execution runs the same checks as the dry run (sufficient funds, position size, well-formed quantities) and refuses trades that would fail, without calling the API.
• Secret redaction. Error text returned to the agent is sanitized; the webhook credential is redacted as defense-in-depth so it cannot leak into transcripts.
• Bearer-secret auth. The webhook ID acts as a bearer token. If it leaks, anyone can act on your account. Don't paste it into screenshots, logs, or chat messages. If you suspect compromise, regenerate it from https://chart.observer/integrations/mcp.
• No account creation. Sign up at https://chart.observer in a browser. Web signup requires a CAPTCHA, which a headless MCP server can't solve.
• Prices are delayed up to 15 minutes. This is a paper-trading platform; quotes must not be used for real-money trading decisions.

What's not in v1

• Real-time push notifications (poll get_portfolio_summary instead).
• Per-token rotation, multiple tokens, scoped tokens, expiry — these will come in a later revision that hardens the webhook-ID lifecycle.
• Equities/options/forex — the platform is crypto-only paper trading today.

Development

npm install
npm run typecheck
npm test
npm run build

To test locally against staging, build then point Claude Desktop at the local file:

{
  "mcpServers": {
    "chartobserver-local": {
      "command": "node",
      "args": ["/absolute/path/to/chartobserver/mcp-server/dist/index.js"],
      "env": {
        "CHARTOBSERVER_API_BASE": "https://g2uyqqluc4.execute-api.us-east-2.amazonaws.com/staging",
        "CHARTOBSERVER_WEBHOOK_ID": "...",
        "CHARTOBSERVER_UID": "...",
        "CHARTOBSERVER_USERNAME": "..."
      }
    }
  }
}

Repo layout

src/
  index.ts          # MCP server entry, registers tools
  config.ts         # Loads + validates env vars
  api-client.ts     # HTTP client for ChartObserver API
  marshal.ts        # Unmarshals raw DynamoDB JSON from the read endpoints
  pairs.ts          # Token-pair resolution + bundled name→symbol map
  instructions.ts   # Agent-facing server instructions
  redact.ts         # Secret-redaction backstop for all outbound error text
  tools/
    account.ts
    trading.ts
    market.ts
    portfolio.ts
    util.ts
  __tests__/
    api-client.test.ts
    config.test.ts
    trading.test.ts
    redact.test.ts