AllocContext
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.
Quick start (Cursor, self-host)
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.
MCP tools
| 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.
Self-host and development
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 [email protected]: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.
Documentation
| 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) |
Contributing
GitHub Issues are welcome for bugs, schema feedback, and MCP API suggestions. Unsolicited pull requests are not expected — see CONTRIBUTING.md.
License
MIT License. Self-host via PyPI. See docs/USE.md.