AllocContext
AllocContext provides portfolio-aware crypto context and allocation analysis tools, delivering deterministic JSON snapshots of holdings, market data, sentiment, macro conditions, and rebalancing math.
get_context_bundle: Retrieve a full snapshot including portfolio holdings, market data, sentiment indicators, macro conditions, regime hints, and delta vs. the prior snapshot. Optionally attach allocation drift analysis by supplying target percentages.get_market_context: Fetch fused market backdrop data — Fear & Greed index, Kalshi sentiment, macro events, FRED indicators, ETF flows, and market breadth — without needing portfolio credentials.get_portfolio_state: Fetch real-time NAV and holdings using read-only exchange API keys (Kraken or Coinbase) or a public EVM wallet address, with optional allocation analysis. Credentials are never stored.get_rebalance_plan: Calculate USD delta moves needed to bring your BTC/ETH/CASH allocation to a target split, with optional band checking and exchange-specific move wording.check_allocation_band: Determine whether your current weights are outside a drift band vs. your target, returning actionable hints likewithin_bandorconsider_rebalance.check_allocation_bands: Evaluate allocation drift against multiple target/band scenarios in a single call.get_context_at: Load a saved ContextBundle from ingest history at a specific ISO timestamp.get_context_delta: Compare two historical ContextBundle snapshots to identify notable shifts in conditions over time.
Provides tools for retrieving live portfolio state (NAV and holdings) from Coinbase exchange accounts.
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 ingestRun 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.
Related MCP server: Web3 Signals — Crypto Signal Intelligence
MCP tools
Tool | Purpose |
| Full ContextBundle — holdings, market, sentiment, macro, delta, regime; optional |
| Sentiment, macro, ETF, breadth, and market fields (no portfolio) |
| Saved snapshot from ingest history at a given |
| Notable shifts between two saved snapshots |
| USD rebalance moves from allocation, target, and NAV |
| Drift vs target and whether allocation is outside the band |
| Batch band checks for multiple target scenarios |
| Live NAV and holdings (CEX keys or public EVM wallet address) |
| 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 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
pytestCommand | Purpose |
| Pull configured sources → SQLite |
| ContextBundle JSON (facts) |
| Per-source ingest ages, snapshots, 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 |
~2 min quickstart | |
Cursor stdio MCP | |
Local ingest + MCP | |
Ingest → rollup → MCP pattern | |
MCP tools | |
Sample tool JSON (redacted) | |
ContextBundle schema | |
License and use policy | |
Local internal MCP + dev ingest | |
Docker Compose self-host | |
PyPI and MCP Registry | |
Release workflow | |
Optional HTTP + x402 (your host) | |
Bridge |
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.
Available Tools
8 toolscheck_allocation_bandB
Check whether BTC/ETH/CASH band weights are outside a drift band vs target_pct and return hint (within_band, consider_rebalance, etc.). All three inputs are required. For bundle drift, pass target_pct on get_context_bundle to attach allocation_analysis.
Inputs: allocation_pct (required), target_pct (required), band. Returns: object
check_allocation_bandsA
Evaluate allocation drift against multiple target_pct/band scenarios in one call. Each scenario needs target_pct; optional name and band (default 0.15).
Inputs: allocation_pct (required), scenarios (required). Returns: object
get_context_atC
Load a saved ContextBundle snapshot from ingest history. as_of is an ISO timestamp; match=at_or_before returns the latest snapshot on or before that time.
Inputs: as_of (required), scope, match, assets, +2 more. Returns: object
get_context_bundleA
Full ContextBundle JSON: portfolio holdings, market, sentiment, macro, regime hints, and delta vs the prior saved snapshot. Optional assets filter (default BTC, ETH). Optional target_pct and band attach allocation_analysis (opt-in drift math). freshness=cached uses the local ingest DB; freshness=live runs ingest first.
Inputs: scope, freshness, assets, target_pct, +1 more. Returns: object
get_context_deltaA
Compare two ContextBundle snapshots and return notable_shifts. prior_as_of is required; omit current_as_of for latest live bundle.
Inputs: prior_as_of (required), scope, current_as_of, assets. Returns: object
get_market_contextA
Fused market backdrop: sentiment (Fear & Greed, Kalshi), macro events, FRED indicators, ETF flows, and market breadth. Optional assets filter (default BTC, ETH). freshness=cached uses the local ingest DB; freshness=live runs ingest first (requires ingest API keys on the host).
Inputs: scope, freshness, assets. Returns: object
get_portfolio_stateA
Live portfolio NAV, holdings[], and band weights from read-only exchange credentials passed in the request. Optional target_pct attaches allocation_analysis. Credentials are never stored. Supports kraken and coinbase.
Inputs: exchange (required), api_key (required), api_secret (required), target_pct, +1 more. Returns: object
get_rebalance_planA
USD deltas and exchange-style move lines to reach a target BTC/ETH/CASH split. Requires allocation_pct, target_pct, and nav_usd. Optional band returns a band_check block alongside the plan. exchange=kraken|coinbase adjusts move wording.
Inputs: allocation_pct (required), target_pct (required), nav_usd (required), exchange, +1 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
get_context_bundle already embeds market context and a delta vs the prior snapshot, so get_market_context and get_context_delta overlap with it. check_allocation_band and check_allocation_bands differ only by plural and both assess drift, creating real selection ambiguity.
All tool names follow a consistent get_/check_ verb + noun snake_case pattern, and the resource names are generally clear. Minor deviations like get_context_at and the near-duplicate singular/plural band-check pair keep it from perfect consistency.
Eight tools is a well-scoped size for an allocation context server. Each tool maps to a recognizable need: context retrieval, market data, portfolio state, rebalance planning, drift checks, and snapshot comparison.
Core read/analyze workflows are covered: current context, market backdrop, portfolio state, rebalance plans, and allocation drift checks. However, there is no tool to list saved snapshots, which makes get_context_at and get_context_delta harder to use without external knowledge of available timestamps.
Maintenance
Related MCP Connectors
Pay-per-call DeFi and macro intel for AI agents. x402 USDC tools via streamable HTTP /api/mcp.
Real-time crypto & tokenized equity intelligence MCP over x402 USDC on Base mainnet.
Paid market-data MCP: crypto, equities, smart-money, macro, wallet PnL. x402 per call on Base.
Otto AI hosted MCP: 16 pay-per-call market-intelligence tools, USDC via x402 on Base, no API keys.
Related MCP Servers
AlicenseAqualityBmaintenanceThe Ultimate Cryptocurrency MCP for AI Assistants - Unified access to crypto, DeFi, and Web3 analytics | MCP Endpoint.1221MIT- AlicenseNot gradedqualityDmaintenanceAI-powered crypto signal intelligence for 20 assets (BTC, ETH, SOL, etc). 6 scoring dimensions: whale activity, technical analysis, derivatives flow, narrative strength, sentiment, market structure. Market regime detection (TRENDING/RANGING), portfolio optimization, and accuracy tracking. 9 read-only MCP tools. Free via MCP, $0.001 USDC via x402 on Base for REST API.3MIT
- FlicenseNot gradedqualityDmaintenance56 pay-per-call MCP endpoints for AI agents. Market signals, macro economics, crypto/DeFi, geopolitical intelligence, SEC filings, GitHub velocity, sanctions screening. USDC on Base Mainnet via x402.-
- AlicenseNot gradedqualityDmaintenanceCrypto intelligence MCP: 104 tools for market data, ML signals, on-chain analytics, derivatives, and Bittensor subnets. Pay-per-call via x402 USDC on Base/Solana/Algorand/Stellar or $9.99/mo API key.MIT