second-brain-ics
An MCP server that lets Claude read calendar feeds: the
secret iCalendar (.ics) links that calendar services hand out for sharing, such as a
Proton Calendar share link. It expands repeating events, handles
moved and cancelled occurrences, time zones and all-day events, and answers in the time zone you
name.
It cannot write. A feed is read-only by nature, and there is no code here that creates, changes or deletes an event or answers an invitation.
A sibling of second-brain-joplin, on the same stack (second-brain-core): FastMCP, stdio for a client on the same machine, streamable HTTP with GitHub sign-in for a Claude custom connector.
Status: 0.1.0. Issues are tracked on the organisation's public tracker, second-brain-joplin.
What Claude gets
| Tool | What it does |
|---|---|
calendar_list |
The calendars: names, how many events, the span of their starts, and how current each one is |
calendar_events |
Occurrences in a date range, repeats expanded, sorted by start, a page at a time |
calendar_search |
Events whose title, place or description holds every word of a query |
calendar_read |
One event, or one occurrence of it, in full: description, organizer, attendees, repeat rule |
Details: docs/tools.md.
What it is careful about
- The feed's address is a secret, and it stays on the server. Anyone who has a share link can read that calendar. Feeds are named in the server's settings, so no tool takes an address (nothing a model reads can make the server fetch a URL), and no log line, error or answer ever carries one. A test plants a marker in every address it uses and fails if it shows up anywhere.
- Bounded fetching. https only; redirects only to https on the same host; one deadline for the whole fetch; a size cap on the decoded body; at most one fetch per feed a minute. When a fetch fails, the last good copy is served, marked stale, with the reason.
- Event text is written by other people (an invitation's title and description are the sender's). Every piece is cleaned of invisible and direction-changing characters, HTML is reduced to the text a reader sees, and every answer says its text is information, not instructions.
- Repeat rules can't stall it. Rules that would take too long to expand are refused, and a call has a time budget.
- No calendar data on disk. The copy of each feed is held in memory only.
- Quiet logs. In HTTP mode, one line per tool call: tool, caller, client, outcome, duration; in either mode, a warning naming the feed when a fetch fails. Never a search term, an event or an address.
More in SECURITY.md.
Try it
uvx second-brain-ics --version
Make a share link (for Proton Calendar: docs/proton-calendar.md), then put it in an env file only you can read:
umask 077
cat > ics.env <<'EOF'
SBICS_FEEDS=personal
SBICS_FEED_PERSONAL=https://calendar.example.com/your/secret/link.ics
SBICS_TIMEZONE=America/Chicago
EOF
uvx second-brain-ics check --env-file ics.env # fetches each feed once, prints counts
Then add it to Claude Code as a stdio server:
claude mcp add second-brain-ics -- uvx second-brain-ics serve --env-file "$PWD/ics.env"
- Settings: docs/configuration.md
- As a Claude custom connector, for claude.ai and the apps: docs/remote-access.md
Development
uv sync
uv run pytest --cov-fail-under=90 # the suite runs its own HTTPS server; no feed needed
uv run mypy
uvx pre-commit run --all-files # ruff lint and format, as CI runs them
uv run scripts/smoke.py --from . # installs the checkout with uvx and talks MCP to it
Sign-in, the audit log, HTTP serving, the settings-file rules and the text cleaner are
second-brain-core's: fix shared code there, release it, then move this package's pin. To try an
unreleased core change, point uv at a checkout for the moment, and don't commit it
([tool.uv.sources] second-brain-core = { path = "../second-brain-core", editable = true }).
More in CONTRIBUTING.md; releasing in docs/releasing.md.
License
Copyright (C) 2026 John McKenzie
second-brain-ics is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. It is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See LICENSE for the full text.
In short: run it and change it as you like. If you pass copies on, or change it and let other people use your version over a network, you must offer them the source under the same license.
Metadata
Release files for second-brain-ics 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| second_brain_ics-0.1.0.tar.gz | 222.4 kB | With provenance | Details for second_brain_ics-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| second_brain_ics-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for second_brain_ics-0.1.0-py3-none-any.whl |
Total release size: 271.4 kB
Release files / second_brain_ics-0.1.0.tar.gz
| Download URL | second_brain_ics-0.1.0.tar.gz |
|---|---|
| Size | 222.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c312f3925eaf7b52ec64f4c50fdfa286de983a39b4da9e3bd16fba53d8f7355e
|
|
BLAKE2b-256 checksum How to use checksums |
317b681dcd2d1ca24d4c92de6585114b22296bbb09deb8df58eab572d788b085
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 22, 2026.
Transparency logRelease files / second_brain_ics-0.1.0-py3-none-any.whl
| Download URL | second_brain_ics-0.1.0-py3-none-any.whl |
|---|---|
| Size | 49.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
8f26c0cbbe243d18213ca0f19f25c41da3fd69e32bc6e765c58622dad16b481c
|
|
BLAKE2b-256 checksum How to use checksums |
0df98fbd4349073ddb89e93f3bf14f7d7c4c2ac54daa1f1ee73541e13bc01018
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 22, 2026.
Transparency logSecurity for second-brain-ics 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for second_brain_ics-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 22, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.