dynamitecircle 1.8.1

Official Python client for the public Dynamite Circle Member API. CLI, library, Agent Skill, and MCP server in one file.

DC Official Client

The official Python client for the Dynamite Circle Member API — your own profile, trips, events, virtual events, tickets, invites, inbox, rooms, chapters, places lookup, and the weekly locator digest.

A single self-contained file. Zero dependencies (stdlib only). Works as a CLI, a Python library, and a Model Context Protocol server. Compatible with Claude Code, Claude Desktop, Codex CLI, Gemini CLI, Cursor, GitHub Copilot, and every other Agent Skills / MCP-compatible tool.

py/dc.py    ← one file, three integration modes

About the Dynamite Circle

The Dynamite Circle is the place where global founders find their people — a curated, members-only community of location-independent business owners running profitable companies around the world. Founded in 2011 (it started with twenty listeners on a remote tropical island), the DC has grown into a hand-selected network of ~1,500 active founders who meet at vetted in-person events like DCBKK and DCMEX, swap notes in private rooms, and travel through each other's home cities year-round.

DC is a private community, but it's open to applications from founders running location-independent businesses doing $100k+ in annual revenue. Every application is personally reviewed by a team member within 48 business hours — start an application here if that sounds like you.

Quick Start

Never used Claude Code, Codex, or git? Here's the 5-minute path from zero to "Claude can read my DC profile."

1. Install the basics (one-time)

You need three free things on your computer:

• Python 3.9+ — the language this client is written in. Download here (Mac/Windows/Linux installers; check "Add Python to PATH" on Windows).
• Git — the tool that downloads code from GitHub. Download here.
• An AI assistant — pick one:
  • Claude Code ← recommended — this repo is built around it
  • Codex CLI — works too, slightly different commands
  • Claude Desktop — the chat app, gets you the MCP server but no CLI

If anything during install asks "do you want to add to PATH?" — say yes.

2. Get the code

Open a terminal:

• Mac: Spotlight → "Terminal"
• Windows: Start → "Terminal" (or "PowerShell")
• Linux: you know what to do

Then paste:

git clone https://github.com/dynamitecircle/dc.git
cd dc

You now have a folder called dc with all the code in it.

3. Get your DC API key

In your browser: go to https://dc.dynamitecircle.com, log in, click your profile photo (top-right), and choose DC Member API Key. Copy the long string starting with dk_….

4. Tell the client about your key

Back in your terminal (still inside the dc folder):

python3 py/dc.py setup --api-key dk_paste_your_key_here

5. Try it

Open Claude Code and make sure it's pointed at the dc folder you just downloaded. (Claude usually opens to your last project — if it's somewhere else, click the folder icon and pick dc.)

Then ask:

"Show me my DC profile"

Claude runs the right command and shows you back your profile. A few more to try:

"What's the latest in DC announcements?" "What events am I attending?" "Show me the DCMEX schedule and bookmark anything about marketing" "Who else from my chapter is going to DCBKK?"

You're done. The rest of this README explains what's possible in more detail; py/SKILL.md lists every command Claude can run.

If something didn't work

Symptom	What to try
python3: command not found	Python didn't install or didn't get added to PATH. Re-install and check the "Add to PATH" box on Windows; on Mac, try python instead of python3.
git: command not found	Same idea — re-install Git.
Claude says "I don't see a dc skill"	Make sure Claude Code is opened to the dc folder, not your home directory or another project. Or just ask Claude: "are you in the dc folder?"
Anything else	Run python3 py/dc.py self-test from the dc folder — it tells you exactly which step is broken.

---

How it's exposed

The same dc.py file is shipped as four integrations — pick whichever fits how your tool talks to it:

Integration	What it is	Invoke with	Dependencies
Agent Skill	Auto-discovered via SKILL.md frontmatter (Claude Code, Codex, Gemini CLI, Cursor, Copilot)	Just open the repo with the tool — it reads py/SKILL.md and offers the commands	stdlib only
CLI	Run commands directly from the shell or scripts	python3 py/dc.py <command>	stdlib only
Python library	Import in your own Python code	from dc import DC; DC().profile()	stdlib only
MCP server	Speaks Model Context Protocol over stdio (Claude Desktop, Cursor, Codex MCP, Cline, etc.)	python3 py/dc.py --mcp	pip install mcp (optional)

The mcp package is lazy-imported — Agent Skill / CLI / Python-library users never need it.

Features

• Full Member API coverage — read + write across every public endpoint (run python3 py/dc.py help for the live list)
• Setup command — saves your API key to a chmod-600 .env.dc next to the skill
• Self-test command — validates env, network, key shape, and a live /profile call end-to-end
• Cursor pagination — every list-returning command uses the same [--limit N] [--cursor TOKEN] shape and returns the canonical envelope {items, count, cursor, has_more}
• Three output formats — text (default, pretty JSON), --json, --python
• MCP-ready — same skill auto-exposes all commands as MCP tools
• Pre-configured for Claude Code — repo ships an .mcp.json, just cd and claude

CLI quickstart (already comfortable in a terminal?)

If you're skipping past the Quick Start above and just want the CLI flow, here's the condensed version.

1. Get an API key

DC profile dropdown → DC Member API Key (admins/testers only). Keys look like dk_<api-key> and are revocable from the same dropdown.

2. Save the key

python3 py/dc.py setup --api-key dk_<api-key>

This writes py/.env.dc (chmod 600, gitignored).

3. Verify the connection

python3 py/dc.py self-test

Expected output:

{
  "ok": true,
  "userID": "<your-id>",
  "displayName": "<Your Name>",
  "checks": [
    { "step": "env",      "ok": true, "message": "DC_API_KEY loaded from ..." },
    { "step": "keyShape", "ok": true, "message": "Key prefix valid (expected userID: <id>)" },
    { "step": "profile",  "ok": true, "message": "connected as userID[<id>] <Your Name>" }
  ]
}

4. Try a few commands

python3 py/dc.py profile
python3 py/dc.py trips --limit 5
python3 py/dc.py events --past --limit 3
python3 py/dc.py chapters --limit 5
python3 py/dc.py permacode

Run python3 py/dc.py help for the full command list.

Setup per AI tool

Claude Code

.mcp.json is already shipped with this repo. Open the repo with claude:

cd dc
claude

Tools become available as mcp__dc__*. First-time install of the optional MCP dependency:

pip install -r py/requirements.txt

Skill discovery (CLI + import) works automatically via py/SKILL.md.

Claude Desktop

Edit your config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "dc": {
      "command": "python3",
      "args": ["/absolute/path/to/dc/py/dc.py", "--mcp"]
    }
  }
}

Restart Claude Desktop.

Codex CLI

Edit ~/.codex/config.toml:

[mcp_servers.dc]
command = "python3"
args = ["/absolute/path/to/dc/py/dc.py", "--mcp"]

Codex auto-discovers AGENTS.md (symlinked to CLAUDE.md) and .agents/skills/ (symlinked to .claude/skills/).

Gemini CLI

Reads GEMINI.md (symlinked to CLAUDE.md) for context. For MCP, configure in your Gemini CLI settings:

mcp_servers:
  dc:
    command: python3
    args:
      - /absolute/path/to/dc/py/dc.py
      - --mcp

Cursor

Settings → MCP → Add server, then point at the same dc.py --mcp.

GitHub Copilot

Reads .github/copilot-instructions.md for context. Copilot doesn't have native MCP support yet — use it for in-editor suggestions while developing.

Any other MCP client

Same recipe: command = python3, args = ["/path/to/dc.py", "--mcp"]. The protocol is standard.

Output formats

python3 dc.py profile             # text (pretty JSON for dicts/lists)
python3 dc.py profile --json      # explicit JSON
python3 dc.py profile --python    # Python repr (eval-safe)

Global flags work before or after the command name:

python3 dc.py --json profile
python3 dc.py profile --json

Cursor pagination

All list-returning commands take the same flags:

python3 dc.py trips
python3 dc.py trips --limit 10
python3 dc.py trips --limit 10 --cursor <opaque-token-from-previous-response>
python3 dc.py trips --past --limit 5

Standard envelope:

{
  "items":    [ /* page of records */ ],
  "count":    42,
  "cursor":   "opaque-token-or-null",
  "has_more": true
}

Non-paginated extras (e.g. totalUnread on inbox) are passed through under an extra key.

Use as a Python library

import sys
sys.path.insert(0, "dc")
from dc import DC

dc = DC()

# Reads
profile  = dc.profile()
trips    = dc.trips(past=True, limit=10)
events   = dc.events(past=True, limit=5)
chapters = dc.chapters()
overlaps = dc.overlaps()
locator  = dc.locator(sections="homeCity,favoriteCities")

# Writes
dc.profile_update({"headline": "CEO at Acme"})
dc.trip_create(start_date="2026-12-01", end_date="2026-12-05", place_id="ChIJ...")
dc.event_rsvp("<eventID>", "yes")
dc.invite_create(email="[e-mail]", full_name="New Friend")

Override the API URL (e.g. for a local dev server):

dc = DC(api_url="http://localhost:8080")

API reference

The full live reference for the DC Member API — every endpoint, parameter, and response shape — is at https://www.dynamitecircle.com/developers/. The page is regenerated on every deploy, so it's always current.

Staying up to date

The DC Member API ships new endpoints and refinements regularly. This skill is the official client and we update it whenever the API changes. Plan for updates — the skill will warn you on stderr the first time a request returns a server X-API-Version newer than DC_API_VERSION, and major-version bumps may break older clients.

Pick whichever integration style fits your project. From simplest to most isolated:

1. Plain git clone — quick local use

git clone https://github.com/dynamitecircle/dc.git
cd dc
python3 py/dc.py setup --api-key dk_<api-key>

To update: cd dc && git pull. Run self-test afterwards.

Best for: trying things out, scripts you run by hand, no other repo involved.

2. Git submodule — pinned to a specific commit

If you have your own project repo and want the dc repo versioned alongside it:

cd your-project
git submodule add https://github.com/dynamitecircle/dc.git vendor/dc
git commit -m "Add dc client as submodule"

To update later:

cd vendor/dc
git pull origin main
cd ../..
git add vendor/dc
git commit -m "Bump dc client"

Then in your code:

import sys
sys.path.insert(0, "vendor/dc/py")
from dc import DC

Best for: production-ish code where you want explicit, reviewable bumps.

3. Git subtree — same updates, no submodule indirection

cd your-project
git subtree add --prefix vendor/dc \
  https://github.com/dynamitecircle/dc.git main --squash

Update with:

git subtree pull --prefix vendor/dc \
  https://github.com/dynamitecircle/dc.git main --squash

Best for: teammates who don't know submodules — files just appear in your repo.

4. Symlink — share one clone across many projects

If you keep all your projects in ~/code/:

git clone https://github.com/dynamitecircle/dc.git ~/code/dc

# In each project that uses it:
cd ~/code/your-project
ln -s ../dc vendor/dc

Now cd ~/code/dc && git pull updates every consumer at once. Project-level .mcp.json / .codex/config.toml entries can use vendor/dc/py/dc.py and they'll resolve through the symlink.

Best for: power users with multiple personal projects and one machine.

5. Pip-installable Git ref — one-shot for a virtualenv

The skill is one file with no setup.py, but you can install the package the MCP server needs and check the file out as a sibling:

pip install mcp
git clone https://github.com/dynamitecircle/dc.git

Best for: CI environments, ephemeral containers, scripted setups.

Update etiquette

• Stay current. The DC Member API ships new endpoints regularly and the client mirrors them; running stale means missing features and (eventually) compatibility warnings on stderr.
• Run self-test after every update. Five seconds, catches breakage.
• Watch stderr the first time you call any command after updating. The version-mismatch warning prints once per process when the server is on a newer minor/major.
• Major version bumps may be backwards-incompatible. Read the release notes on the GitHub repo before pulling across a major boundary.

Rate limits

Tier	Per minute	Per day
DC Community	10	300
DC BLACK	60	3,000

Headers on every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, X-RateLimit-Daily-Remaining.

Platform support

Tested on macOS, Linux, and Windows 10/11. Python 3.9+ required (uses pathlib, Path.replace, inspect.signature, contextvars, urllib).

Windows notes

• The skill auto-reconfigures stdout and stderr to UTF-8 at startup, so emoji and em-dashes render correctly even on legacy cmd.exe (which defaults to cp1252). If you still see mojibake on a very old terminal, set PYTHONIOENCODING=utf-8 once: setx PYTHONIOENCODING utf-8 then restart your shell.
• setup writes .env.dc and tries to chmod 600 it. On Windows this is a no-op — the file inherits NTFS perms from its parent. The skill emits a one-time note about this when you run setup. Make sure your repo isn't on a shared drive.
• Use python or python3.exe to invoke; the #!/usr/bin/env python3 shebang is ignored on Windows.

Project layout

dc/
├── README.md                          # this file
├── CLAUDE.md                          # AI-tool guide (also linked as AGENTS.md, GEMINI.md)
├── AGENTS.md       → CLAUDE.md        # symlink (Codex)
├── GEMINI.md       → CLAUDE.md        # symlink (Gemini)
├── LICENSE                            # MIT
├── manifest.json                      # MCPB manifest (MCP 2025-11 spec)
├── .mcp.json                          # auto-registers `dc` MCP server in Claude Code
├── .codex/
│   └── config.toml                    # auto-registers `dc` for Codex CLI
├── .github/
│   └── copilot-instructions.md        # GitHub Copilot
│
├── py/                                # ← Python client (canonical)
│   ├── SKILL.md                       # Agent Skills frontmatter + usage
│   ├── config.json                    # name, version, env requirements
│   ├── dc.py                          # CLI + Python import + --mcp server
│   ├── requirements.txt               # optional MCP dep — skip for CLI/import
│   ├── .env.dc.example                # template
│   └── .env.dc                        # gitignored (created by `setup`)
│
│   (Future: go/, node/, rs/ folders for sister clients in other languages)
│
├── docs/                              # ← REAL design docs (canonical)
│   ├── skill-info.md                # design rules / architecture
│   └── mcp-info.md                    # MCP setup for every supported client
│
├── .claude/                           # Agent Skills discovery (Claude Code)
│   ├── skills/dc  → ../../py          # symlink to canonical Python client
│   └── docs       → ../docs           # symlink to canonical docs
│
├── .agents/                           # Agent Skills discovery (Codex CLI + Gemini CLI alias)
│   ├── skills/dc  → ../../py          # symlink to canonical Python client
│   └── docs       → ../docs           # symlink to canonical docs
│
├── .gemini/                           # Gemini CLI MCP config
│   └── settings.json                  # auto-approves dc MCP tools (trust: true)
│
├── .gitignore
└── .gitattributes

About the layout

This is a monorepo. The Python client lives at /py/ so we can add future sister clients (go/, node/, rs/) at the same level — they all wrap the same DC Member API. /docs/ is shared. The dotfile-prefixed directories (.claude/, .agents/, .gemini/) exist because AI tools auto-discover skills from those specific paths — they're kept hidden but each one symlinks (or points) straight to the canonical folder, so you only edit files in one place. Edit py/dc.py and Claude Code, Codex, and Gemini CLI all see the same file via their respective discovery directories. Gemini CLI also reads .agents/skills/ as an alias, so we don't need a redundant .gemini/skills/ symlink.

If you're adding new code or docs, edit py/ (or docs/) directly. The discovery folders take care of themselves.

Pre-approval out of the box

.claude/settings.json, .codex/config.toml, and .gemini/settings.json all auto-approve the dc MCP server's tools so users don't get a per-call approval prompt when they open this repo with their AI tool. Anyone uncomfortable with that can override with their personal .claude/settings.local.json, ~/.codex/config.toml, or ~/.gemini/settings.json. Every dc write tool is scoped to the caller's own DC account via their personal API key — pre-approval doesn't widen any blast radius, just removes per-call friction.

Maintenance

This repo is maintained by the Dynamite Circle team. It's read-only for the public — clone it and use it, but don't open PRs. If you spot a bug or want a new feature, contact us through the official DC channels.

License

MIT — see the LICENSE file for the full text.