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.
[](https://github.com/jerryj6/htmw-mcp/actions/workflows/ci.yml)

[](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
[](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.
This server cannot be deployed
Maintenance
ActivityNo data
ResponsivenessOutdated data