Self-host MCP: portfolio crypto context for agents. PyPI stdio; MIT.
mcp-name: io.github.AllocContext/alloc-context
Portfolio-aware crypto context for whatever you hold — discover your holdings, holdings-scoped market data, sentiment, macro, and regime; optional allocation analysis when you supply targets. Deterministic JSON over MCP.
New here? Cursor MCP setup — stdio in your editor, or self-hosting with local ingest. Organization: AllocContext on GitHub.
Privacy: nothing stored · one-time read-only · pass-through only when using live portfolio reads. See USE.md.
1. Install
pip install "alloc-context[mcp]"
# From source: pip install -e ".[mcp]"
2. Config and secrets
Copy config/config.example.yaml to
config/config.yaml. Copy .env.example to .env and add
read-only exchange keys when you want portfolio ingest or macro feeds.
See self-hosting.md.
3. MCP config
Add to your global ~/.cursor/mcp.json:
{
"mcpServers": {
"alloc-context": {
"command": "alloc-context",
"args": [
"--config",
"/absolute/path/to/alloc-context/config/config.yaml",
"mcp"
],
"env": {
"ALLOC_CONTEXT_DB": "/absolute/path/to/alloc-context/state/alloccontext.db"
}
}
}
}
Use absolute paths. See cursor-mcp.example.json.
4. Refresh facts (optional)
python -m alloccontext --config config/config.yaml ingest
Run before a session or when you want fresh macro/regime data. No cron required.
5. Ask your agent
Call get_context_bundle for a full snapshot. Pure math tools
(check_allocation_band, get_rebalance_plan) work without portfolio credentials.
Full setup: cursor-mcp.md. Samples: examples.md.
Not financial advice.
| Tool | Purpose |
|---|---|
get_context_bundle | Full ContextBundle — holdings, market, sentiment, macro, delta, regime; optional allocation_analysis |
get_market_context | Sentiment, macro, ETF, breadth, and market fields (no portfolio) |
get_context_at | Saved snapshot from ingest history at a given as_of |
get_context_delta | Notable shifts between two saved snapshots |
get_rebalance_plan | USD rebalance moves from allocation, target, and NAV |
check_allocation_band | Drift vs target and whether allocation is outside the band |
check_allocation_bands | Batch band checks for multiple target scenarios |
get_portfolio_state | Live NAV and holdings (CEX keys or public EVM wallet address) |
get_expectation_review | Score optional local theses against context (pass-through) |
Market context is holdings-scoped: band assets (BTC/ETH) use OHLC bars; alt holdings (e.g. HYPE) use quote snapshots when cached. See context-bundle.md#market-coverage.
See mcp.md for arguments and resources.
Run ingest and MCP on your machine — the primary supported path.
See self-hosting.md, local-dev.md
(./scripts/dev-up.sh), or docker-self-host.md.
git clone git@github.com:AllocContext/alloc-context.git
cd alloc-context
python3.11 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev,mcp]"
cp .env.example .env
cp config/config.example.yaml config/config.yaml
python -m alloccontext ingest --dry-run
python -m alloccontext rollup --scope daily --stdout
pytest
| Command | Purpose |
|---|---|
python -m alloccontext ingest | Pull configured sources → SQLite |
python -m alloccontext rollup --scope daily --stdout | ContextBundle JSON (facts) |
python -m alloccontext status | Per-source ingest ages, snapshots, MCP /health |
alloc-context mcp | MCP server (stdio or HTTP) |
Optional HTTP MCP + x402 on your host: mcp-http.md.
AllocContext is self-host only — we do not operate mcp.alloc-context.com.
Quickstart: agent-onramp.md · cursor-mcp.md.
| Document | Purpose |
|---|---|
| docs/agent-onramp.md | ~2 min quickstart |
| docs/cursor-mcp.md | Cursor stdio MCP |
| docs/self-hosting.md | Local ingest + MCP |
| docs/deterministic-context-mcp-pattern.md | Ingest → rollup → MCP pattern |
| docs/mcp.md | MCP tools |
| docs/examples.md | Sample tool JSON (redacted) |
| docs/context-bundle.md | ContextBundle schema |
| docs/USE.md | License and use policy |
| docs/local-dev.md | Local internal MCP + dev ingest |
| docs/docker-self-host.md | Docker Compose self-host |
| docs/distribution.md | PyPI and MCP Registry |
| docs/publishing.md | Release workflow |
| docs/mcp-http.md | Optional HTTP + x402 (your host) |
| docs/user-config.md | Bridge user.yaml (legacy archive) |
GitHub Issues are welcome for bugs, schema feedback, and MCP API suggestions. Unsolicited pull requests are not expected — see CONTRIBUTING.md.
MIT License. Self-host via PyPI. See docs/USE.md.
Source-derived launch command. Check the maintainer’s required arguments and credentials before running:
uvx alloc-contextMerge this template into ~/Library/Application Support/Claude/claude_desktop_config.json. Keep existing servers. Add any arguments, credentials, and permissions required by the maintainer; this template has not been install-tested.
{
"mcpServers": {
"io-github-alloccontext-alloc-context": {
"command": "uvx",
"args": [
"alloc-context"
]
}
}
}Restart Claude Desktop completely for changes to take effect. Confirm the server appears connected in the client’s tool list, then try a read-only example from its documentation.
Claude Desktop setup referenceAllocContext works with any MCP-compatible client. Copy the config snippet from the Configuration section above and add it to the file shown for your client, then restart the application.
~/Library/Application Support/Claude/claude_desktop_config.jsonRestart Claude Desktop completely for changes to take effect.~/.cursor/mcp.jsonRestart Cursor for changes to take effect..vscode/mcp.jsonReload VS Code window for changes to take effect.~/.codeium/windsurf/mcp_config.jsonRestart Windsurf for changes to take effect..mcp.jsonSave at the project root, then start Claude Code in that project and review the MCP server approval prompt. Keep real credentials out of shared files.