Skip to main content
Glama
HTMW MCP
by jerryj6
README.md
# HTMW MCP

Connect your [HowTheMarketWorks](https://www.howthemarketworks.com) simulator account to an AI assistant through the Model Context Protocol.

[![CI](https://github.com/jerryj6/htmw-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/jerryj6/htmw-mcp/actions/workflows/ci.yml)
![Node.js 22+](https://img.shields.io/badge/Node.js-22%2B-417E38)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

Read your portfolio, look up quotes, search symbols, inspect orders and transaction history, and check contest rankings. You can also place or cancel a simulated order after explicitly requesting it. The server provides nine tools over stdio or authenticated HTTP.

```text
Your MCP client → HTMW MCP → Your HowTheMarketWorks account
```

## Run locally

You need **Node.js 22 or newer**, npm, and an HTMW account with an active contest.

```sh
git clone https://github.com/jerryj6/htmw-mcp.git
cd htmw-mcp
npm ci --ignore-scripts
npm run build
```

Add this to an MCP client's `mcpServers` configuration, replacing the path and credentials:

```json
{
  "mcpServers": {
    "htmw": {
      "command": "node",
      "args": ["/absolute/path/to/htmw-mcp/dist/index.js"],
      "env": {
        "HTMW_USERNAME": "your_username",
        "HTMW_PASSWORD": "your_password"
      }
    }
  }
}
```

Restart the client and ask: **“Show my HTMW portfolio.”** See the copyable [stdio configuration](examples/stdio.json). Configuration location varies by client; it must support MCP servers over stdio. On Windows, use an absolute path such as `C:/Users/you/htmw-mcp/dist/index.js`.

For terminal use, copy `.env.example` to `.env`, fill in your credentials, and run `npm start`. This starts a stdio protocol server that waits for an MCP client; it is not an interactive terminal prompt. Login happens on the first account request.

## Deploy your own server

[![Deploy to Render](https://render.com/images/deploy-to-render-button.svg)](https://render.com/deploy?repo=https%3A%2F%2Fgithub.com%2Fjerryj6%2Fhtmw-mcp)

Click the button, supply your HTMW username and password, and deploy. Render generates an `MCP_AUTH_TOKEN`; copy it from your service's environment settings. Connect your MCP client with:

| Setting   | Value                                       |
| --------- | ------------------------------------------- |
| Transport | Streamable HTTP                             |
| URL       | `https://YOUR-SERVICE.onrender.com/mcp`     |
| Header    | `Authorization: Bearer YOUR_MCP_AUTH_TOKEN` |

Your client must support custom authorization headers. Each deployment connects to **one HTMW account**; anyone holding its token can use that account's tools. This repository contains source code for your own instance, not a shared account endpoint.

Prefer self-hosting? [Use Docker Compose](docs/deployment.md#docker-compose), or follow the [HTTP and Render guide](docs/deployment.md). No database is required. Render instances created with the button use manual deploys so you can choose when to update them.

## Available tools

| Tool                      | Purpose                                                     |
| ------------------------- | ----------------------------------------------------------- |
| `get_portfolio`           | Balances, positions, and open orders                        |
| `get_quote`               | Quote for a stock symbol                                    |
| `search_symbol`           | Find symbols by company name or ticker                      |
| `get_open_orders`         | Pending orders and their IDs                                |
| `get_transaction_history` | Transactions over a chosen lookback                         |
| `list_tournaments`        | Contests available to the account                           |
| `get_contest_rankings`    | Top five, bottom five, and your rank when identifiable      |
| `execute_trade`           | Place a requested simulated order; requires `confirm: true` |
| `cancel_order`            | Cancel a requested order; requires `confirm: true`          |

See [tool inputs, examples, and account behavior](docs/tools.md). Orders and portfolio data use the account currently selected on HTMW. Starting the server runs no trading strategy or background scans.

## Troubleshooting

- **Missing credentials:** pass `HTMW_USERNAME` and `HTMW_PASSWORD` in the client configuration, or place them in `.env` in the server's working directory.
- **HTTP 401:** send your deployment's bearer token on each MCP request.
- **HTTP 403:** configure your browser client's exact origin in `MCP_ALLOWED_ORIGINS`.
- **Cold start:** an idle free Render instance may take time to wake up. Check `https://YOUR-SERVICE.onrender.com/health`, then reconnect.
- **Login or parsing errors:** verify your account directly on HTMW. The integration uses website endpoints, so upstream changes may need parser updates. See the [deployment guide](docs/deployment.md).

## Develop and contribute

```sh
npm ci --ignore-scripts
npm run check
```

Checks cover formatting, TypeScript, and mocked regression and transport tests. They do not access an HTMW account or place simulator orders. See [development](docs/development.md), [contributing](CONTRIBUTING.md), and [release notes](CHANGELOG.md).

## License

[MIT](LICENSE). Unofficial integration; not affiliated with HowTheMarketWorks.